API accessability via HTTPS custom domain - ActoKids/api GitHub Wiki

AWS offers "edge optimized" and "regional" API deployment options. A "regional" API endpoint is accessed from the same AWS region in which the API itself is deployed; an "edge-optimized" endpoint is accessed via a CloudFront distribution (i.e. via a CDN). Then, when you create a custom domain for the API, you are once again given the option of choosing an "edge-optimized" or "regional" endpoint configuration. The custom domain endpoint configuration will supersede the original endpoint configuration. See this Stack Overflow thread for a more detailed explanation: https://stackoverflow.com/questions/49826230/regional-edge-optimized-api-gateway-vs-regional-edge-optimized-custom-domain-nam

Steps to create a custom domain for an API Gateway API

  1. Register a domain name using the registrar of your choice.

  2. Create a Hosted Zone in AWS Route 53 -- note the nameservers (NS) values provided.

  3. If the domain was registered using something other than AWS Route 53 (e.g. Google Domains), use the management tools of the third-party registrar to configure custom nameservers. Replace the default values with those provided by AWS.

  4. Use AWS Certificate Manager to request a certificate. NOTE: If you are setting up an "Edge-optimized" API, you must request a certificate from within the US East (N. Virginia) region, even if the API is hosted elsewhere. However, if you are setting up a "Regional API", you must request a certificate from the SAME region in which the API is hosted. Change to the appropriate region before proceeding.

    • Click "Request Certificate".
    • On the next page, select "Request a public certificate" and click the "Request a certificate button"
    • On the "Add domain names" page, enter the domain name for the api -- e.g. api.example.com
    • On the "Select Validation Method" page, select "DNS validation" and click "Review".
    • If all looks good, select "Confirm and Request". NOTE: At this point, you may encounter an error that reads, "Something went wrong. Cannot request more certificates in this account. Contact Customer Service for details". This is a known bug -- see this forum thread for details: https://forums.aws.amazon.com/thread.jspa?messageID=867556 . To resolve the issue, you must contact Customer Support and request that they increase the limit on the number of certificates you can request.
    • On the next page, the validation status for your domain will be "Pending validation". Click the black arrow beside your domain name and click, "Create record in Route 53". A modal will appear. Click "Create".
    • Click "Continue". Status will say "Pending validation" for up to 30 minutes. You may need to refresh the page to see the updated status.

  5. Once you have a valid certificate, return to the region where your API is hosted (if necessary) and open the API Gateway console.

    • Select "Custom Domain Names" from the menu on the left
    • Click "Create Custom Domain Name"
    • Select "HTTP" and enter your domain name (e.g. api.example.com)
    • Select "Edge optimized" or "Regional", as appropriate.
    • Select your newly-created certificate from the drop-down.
    • Click "Save". Note: If you are creating an edge-optimized endpoint configuration, it make take up to 40 minutes to initialize.
    • Once the custom domain name has been created, click "Show Base Path Mappings" and add one or more base paths. For the Path, specify a version (e.g. /v1); for the Destination, select the API that you wish to attach to the custom endpoint; and for the Stage, select your active deployment stage (e.g. prod, dev, default).

  6. Copy the "Target Domain Name" and go to the Route 53 console.

    • Go to the Hosted Zone for your domain
    • Click "Create Record Set"
    • For Name, enter "api" (the record you create will be api.yourdomainname.whatever)
    • For Alias, select "Yes"
    • For Alias Target, enter the Target Domain Name that you copied from the API gateway
    • Click create

  7. Test your API in the browser. If you added a base path of v1, and your API Resource was called "ping", you would enter the following: https://api.yourdomainname.whatever/v1/ping. If everything went smoothly, the browser should return the expected response from a secure connection. Note: custom endpoints attached to regional APIs do not automatically redirect http requests to https