How do I connect to a private API Gateway over a Direct Connect connection?

Resolution

Create an Amazon Virtual Private Cloud (Amazon VPC) endpoint for the Amazon API Gateway service

An Amazon VPC endpoint allows private resources in a VPC to securely communicate with the API Gateway service. To create an Amazon VPC endpoint for API Gateway:

1. Open the Amazon VPC console.
2. In the navigation pane, under Virtual Private Cloud, choose Endpoints.
3. For Service Category, choose AWS Services.
4. For Service Name, search by keyword for "execute-api". This returns a single result: "com.amazonaws.REGION.execute-api".
5. Select "com.amazonaws.REGION.execute-api".
6. For VPC, select the Amazon VPC where your Direct Connect connection is configured.
7. For Subnets, select the subnets where you want the API to be accessible.
8. For Enable DNS name, clear the Enable for this endpoint box. Disabling this setting requires that the Amazon VPC has "DNS hostnames" enabled, which is an optional feature. Leaving this setting enabled breaks all access to public API Gateway APIs in the deployed Amazon VPC if the VPC uses the Amazon provided DNS.
9. For Security group, choose the security group for the Amazon VPC endpoint. The security group must allow access on TCP/443 inbound from your Amazon VPC.
10. For Policy, choose Full Access. This option allows all connections from your Amazon VPC to the VPC endpoint using AWS IAM permissions.
11. Choose Create Endpoint.
12. Note the Amazon VPC Endpoint ID (for example, "vpce-01234567890abcdef"). You need this ID later to edit the API's resource policy.

Create your private REST API, if you don't already have one

1. Open the API Gateway console.
2. Select the Region of your Direct Connect connection.
3. Choose Create API.
4. For API type, choose REST API Private.
5. For API protocol, choose REST.
6. Under Create a New API, choose Example API.
7. Under Settings, confirm that Endpoint Type is set to Private.
8. Choose Import.

Grant the Amazon VPC endpoint permission to access the private REST API

1. On the API Management page, choose Resource Policy.
2. Copy the policy below into your Resource Policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Principal": "*",
            "Action": "execute-api:Invoke",
            "Resource": "execute-api:/*/*/*",
            "Condition": {
                "StringNotEquals": {
                    "aws:sourceVpce": "{{vpceID}}"
                }
            }
        },
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": "execute-api:Invoke",
            "Resource": "execute-api:/*/*/*"
        }
    ]
}

Replace the {{vpceID}} string with the Amazon VPC Endpoint ID that you noted after creating the VPC endpoint. Or, find the ID in the Amazon VPC console under Endpoints.
Note: This example policy allows access to all resources on the API from your Amazon VPC. To further restrict access, modify the Resource key.

3.    Choose Save.

Deploy your API to commit the changes

Now that you've created the API and added a resource policy, you must deploy the API to a stage to implement your changes. To deploy your API to a stage:

1. In the API Gateway console, choose Resources from the navigation pane.
2. Choose Actions.
3. Under API Actions, choose Deploy API.
4. For Deployment stage, choose [New Stage].
5. Enter a name for the stage.
6. Choose Deploy. The changes are deployed to the API. This process can take a few minutes to propagate.

Test access to the API from the Direct Connect connection

1. On the Amazon VPC console, choose Endpoints, and then select the VPC endpoint that you created.
2. Under Details, copy the DNS name for the VPC endpoint. For example,
   "vpce-0123456789abcdef-b238e1kf.execute-api.REGION.vpce.amazonaws.com".
3. From a computer with a connection to your Amazon VPC using Direct Connect, run one of the following commands to test the DNS hostname resolution of the VPC endpoint.

Windows PowerShell:

nslookup <YOUR_VPCE_HOSTNAME>

-or-

macOS/Unix:

nslookup <YOUR_VPCE_HOSTNAME>

The response should return a private IP address that corresponds to your Amazon VPC endpoint. If you don't receive a private IP address in the response, then check the Amazon VPC endpoint hostname on the Amazon VPC console under Endpoints.

4.    If DNS is working, then make a test HTTP request. To do this, you need the API ID from the API Gateway console. Copy the API ID from the list. The API ID is a string of characters, such as "chw1a2q2xk".

5.    From an on-premises computer connected to the Direct Connect connection, run the following command:

Windows PowerShell:

curl -H @{'x-apigw-api-id' = '<YOUR_API_ID>'} https://<YOUR_VPCE_HOSTNAME>/<STAGE>

-or-

macOS/Unix:

curl -IX GET -H 'x-apigw-api-id:<YOUR_API_ID>' https://<YOUR_VPCE_HOSTNAME>/<STAGE>

The first line of the response should include "HTTP/1.1 200 OK".

If you don't receive a response, then check that the security group associated with the Amazon VPC endpoint allows inbound connections on TCP/443 from your source IP address. Also check that your connection is correctly using your Direct Connect connection.

If you're receiving a "403 Forbidden" response, then check that you have set the <YOUR_API_ID> header. Confirm that you're sending a GET request. Also, check that the <STAGE> was correctly added.

Related information

How can I troubleshoot Direct Connect gateway routing issues?

How can I set up a Direct Connect gateway?