Set up an API Gateway API with private integrations using the Amazon CLI

To set up an API with the private integration using Amazon CLI

1. The following create-vpc-link command creates a VpcLink targeting the specified Network Load Balancer.

   aws apigateway create-vpc-link \
       --name my-test-vpc-link \
       --target-arns arn:aws-cn:elasticloadbalancing:us-west-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef

   The output of this command acknowledges the receipt of the request and shows the PENDING status for the VpcLink being created.

   {
       "status": "PENDING", 
       "targetArns": [
           "arn:aws-cn:elasticloadbalancing:us-west-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef"
       ], 
       "id": "gim7c3", 
       "name": "my-test-vpc-link"
   }

   It takes 2-4 minutes for API Gateway to finish creating the VpcLink. When the operation finishes successfully, the status is AVAILABLE. You can verify this by calling the following get-vpc-link command:

   aws apigateway get-vpc-link --vpc-link-id gim7c3

   If the operation fails, you get a FAILED status, with the statusMessage containing the error message. For example, if you attempt to create a VpcLink with a Network Load Balancer that is already associated with a VPC endpoint, you get the following on the statusMessage property:

   "NLB is already associated with another VPC Endpoint Service"

   After the VpcLink is created successfully, you can create an API and integrate it with the VPC resource through the VpcLink.

   Note the id value of the newly created VpcLink. In this example output, it's gim7c3. You need it to set up the private integration.

2. The following create-rest-api command creates an API Gateway RestApi resource:

   aws apigateway create-rest-api --name 'My VPC Link Test'

   Note the RestApi's id value and the RestApi's rootResourceId value in the returned result. You need this value to perform further operations on the API.

   For illustration purposes, we will create an API with only a GET method on the root resource (/) and integrate the method with the VpcLink.

3. Set up the GET / method. Use the following put-method command and enter the Id as the rest-api-id and the rootResourceId as the resource-id:

   aws apigateway put-method \
          --rest-api-id  abcdef123 \
          --resource-id skpp60rab7 \
          --http-method GET \
          --authorization-type "NONE" 

   If you don't use the proxy integration with the VpcLink, you must also set up at least a method response of the 200 status code. We will use the proxy integration here.

4. After you create the GET / method, you set up the integration. For a private integration, you use the connection-id parameter to provide the VpcLink ID. You can use either a stage variable or directly enter the VpcLink ID. The uri parameter is not used for routing requests to your endpoint, but is used for setting the Host header and for certificate validation.

   Use the VPC link ID

   The following put-integration command uses the VpcLink ID directly in the integration:

   aws apigateway put-integration \
       --rest-api-id abcdef123 \
       --resource-id skpp60rab7 \
       --uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-west-2.amazonaws.com' \
       --http-method GET \
       --type HTTP_PROXY \
       --integration-http-method GET \
       --connection-type VPC_LINK \
       --connection-id gim7c3

   Use a stage variable

   The following put-integration command uses a stage variable to reference the VPC link ID. When you deploy your API to a stage, you set the VPC link ID.

   aws apigateway put-integration \
       --rest-api-id abcdef123 \
       --resource-id skpp60rab7 \
       --uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-west-2.amazonaws.com' \
       --http-method GET \
       --type HTTP_PROXY \
       --integration-http-method GET \
       --connection-type VPC_LINK \
       --connection-id "\${stageVariables.vpcLinkId}"

   Make sure to double-quote the stage variable expression (${stageVariables.vpcLinkId}) and escape the $ character.

   At any point, you can also update the integration to change the connection-id. The following update-integration command shows how to update your integration:

    aws apigateway update-integration \
       --rest-api-id abcdef123 \
       --resource-id skpp60rab7 \
       --http-method GET \
       --patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]'  

   Make sure to use a stringified JSON list as the patch-operations parameter value.

   Because we used the private proxy integration, your API is now ready for deployment and for test runs. With the non-proxy integration, you must also set up the method response and integration response, just as you would when setting up an API with HTTP custom integrations.

5. If you used the stage variable to define your connection-id, you need to deploy your API to test it. The following create-deployment command shows how to deploy your API with a stage variable:

   aws apigateway create-deployment \
       --rest-api-id abcdef123 \
       --stage-name test \
       --variables vpcLinkId=gim7c3

   To update the stage variable with a different VpcLink ID, such as asf9d7, call the update-stage command:

   aws apigateway update-stage \
       --rest-api-id abcdef123 \
       --stage-name test \
       --patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7'

   When you hardcode the connection-id property with the VpcLink ID literal, you don't need to deploy your API to test it. Use the test-invoke-method command to test your API before it is deployed.

6. Use the following command to invoke your API:

   curl -X GET https://abcdef123.execute-api.us-west-2.amazonaws.com/test

   Alternatively, you can enter your API's invoke-URL in a web browser to view the result.