Menu
Amazon API Gateway
Developer Guide

Build an API with API Gateway Private Integration

You can create an API Gateway API with private integration to provide your customers access to HTTP/HTTPS resources within your Amazon Virtual Private Cloud (Amazon VPC). Such VPC resources are HTTP/HTTPS endpoints on an EC2 instance behind a network load balancer in the VPC. The network load balancer encapsulates the VPC resource and routes incoming requests to the targeted resource.

When a client calls the API, API Gateway connects to the network load balancer through the pre-configured VPC link. A VPC link is encapsulated by an API Gateway resource of VpcLink. It is responsible for forwarding API method requests to the VPC resources and returns backend responses to the caller. For an API developer, a VpcLink is functionally equivalent to an integration endpoint.

To create an API with private integration, you must create a new or choose an existing VpcLink connected to a network load balancer that targets the desired VPC resources. You must have appropriate permissions to create and manage a VpcLink. You then set up an API method and integrate it with the VpcLink by setting either HTTP or HTTP_PROXY as the integration type, setting VPC_LINK as the integration connection type, and setting the VpcLink identifier on the integration connectionId.

To quickly get started creating an API to access VPC resources, we walk through the essential steps for building an API with the private integration, using the API Gateway console. Before creating the API, do the following:

  1. Create a VPC resource, create or choose a network load balancer under your account in the same region, and add the EC2 instance hosting the resource as a target of the network load balancer. For more information, see Set up a Network Load Balancer for API Gateway Private Integrations.

  2. Grant permissions to create the VPC links for private integrations. For more information, see Grant Permissions to Create a VPC Link.

After creating your VPC resource and your network load balancer with your VPC resource configured in its target groups, use the following instructions below to create an API and integrate it with the VPC resource via a VpcLink in a private integration.

To create an API with private integration using the API Gateway console

  1. Sign in to the API Gateway console and choose a region; for example, us-west-2, on the navigation bar.

  2. Create a VPC link, if you have not already done so:

    1. From the primary navigation pane, choose VPC Links and then choose + Create.

    2. Under VPC Link, type a name (for example, my-test-vpc-link) in the Name field.

    3. Optionally, give a description of the VPC link in the Description text area.

    4. Choose a network load balancer from the Target NLB drop-down list.

      You must have the network load balancer already created in the region you chose for the network load balancer to be present in the list.

    5. Choose Create to start creating the VPC link.

    The initial response returns a VpcLink resource representation with the VPC link ID and a PENDING status. This is because the operation is asynchronous and takes about 2-4 minutes to complete. Upon successful completion, the status is AVAILABLE. In the meantime, you can proceed to create the API.

  3. Choose APIs from the primary navigation pane and then choose + Create API to create a new API of either an edge-optimized or regional endpoint type.

  4. For the root resource (/), choose Create Method from the Actions drop-down menu, and then choose GET.

  5. In the / GET - Setup pane, initialize the API method integration as follows:

    1. Choose VPC Link for Integration type.

    2. Choose Use Proxy Integration.

    3. From the Method drop-down list, choose GET as the integration method.

    4. From the VPC Link drop-down list, choose [Use Stage Variables] and type ${stageVariables.vpcLinkId} in the text box below.

      We will define the vpcLinkId stage variable after deploying the API to a stage and set its value to the ID of the VpcLink created in Step 1.

    5. Type a URL, for example, http://myApi.example.com, for Endpoint URL.

      Here, the host name (for example, myApi.example.com) is used to set the Host header of the integration request.

    6. Leave the Use Default Timeout selection as-is, unless you want to customize the integration timeouts.

    7. Choose Save to finish setting up the integration.

      With the proxy integration, the API is ready for deployment. Otherwise, you need to proceed to set up appropriate method responses and integration responses.

    8. From the Actions drop-down menu, choose Deploy API and then choose a new or existing stage to deploy the API.

      Note the resulting Invoke URL. You need it to invoke the API. Before doing that, you must set up the vpcLinkId stage variable.

    9. In the Stage Editor, choose the Stage Variables tab and choose Add Stage Variable.

      1. Under the Name column, type vpcLinkId.

      2. Under the Value column, type the ID of VPC_LINK, for example, gix6s7.

      3. Choose the check-mark icon to save this stage variable.

        Using the stage variable, you can easily switch to different VPC links for the API by changing the stage variable value.

      This completes creating the API. You can test invoking the API as with other integrations.