# Create integrations for HTTP APIs in API Gateway *Integrations* connect a route to backend resources. HTTP APIs support Lambda proxy, AWS service, and HTTP proxy integrations. For example, you can configure a `POST` request to the `/signup` route of your API to integrate with a Lambda function that handles signing up customers. **Topics** + [ # Create AWS Lambda proxy integrations for HTTP APIs in API Gateway ](http-api-develop-integrations-lambda.md) + [ # Create HTTP proxy integrations for HTTP APIs ](http-api-develop-integrations-http.md) + [ # Create AWS service integrations for HTTP APIs in API Gateway ](http-api-develop-integrations-aws-services.md) + [ # Create private integrations for HTTP APIs in API Gateway ](http-api-develop-integrations-private.md) # Create AWS Lambda proxy integrations for HTTP APIs in API Gateway A Lambda proxy integration enables you to integrate an API route with a Lambda function. When a client calls your API, API Gateway sends the request to the Lambda function and returns the function's response to the client. For examples of creating an HTTP API, see [Create an HTTP API](http-api-develop.md#http-api-examples). ## Payload format version The payload format version specifies the format of the event that API Gateway sends to a Lambda integration, and how API Gateway interprets the response from Lambda. If you don't specify a payload format version, the AWS Management Console uses the latest version by default. If you create a Lambda integration by using the AWS CLI, CloudFormation, or an SDK, you must specify a `payloadFormatVersion`. The supported values are `1.0` and `2.0`. For more information about how to set the `payloadFormatVersion`, see [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html). For more information about how to determine the `payloadFormatVersion` of an existing integration, see [get-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-integration.html) ### Payload format differences The following list shows differences between the `1.0` and `2.0` payload format versions: + Format `2.0` doesn't have `multiValueHeaders` or `multiValueQueryStringParameters` fields. Duplicate headers are combined with commas and included in the `headers` field. Duplicate query strings are combined with commas and included in the `queryStringParameters` field. + Format `2.0` has `rawPath`. If you use an API mapping to connect your stage to a custom domain name, `rawPath` won't provide the API mapping value. Use format `1.0` and `path` to access the API mapping for your custom domain name. + Format `2.0` includes a new `cookies` field. All cookie headers in the request are combined with commas and added to the `cookies` field. In the response to the client, each cookie becomes a `set-cookie` header. ### Payload format structure The following examples show the structure of each payload format version. All headernames are lowercased. ------ #### [ 2.0 ] ``` { "version": "2.0", "routeKey": "$default", "rawPath": "/my/path", "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", "cookies": [ "cookie1", "cookie2" ], "headers": { "header1": "value1", "header2": "value1,value2" }, "queryStringParameters": { "parameter1": "value1,value2", "parameter2": "value" }, "requestContext": { "accountId": "123456789012", "apiId": "api-id", "authentication": { "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "authorizer": { "jwt": { "claims": { "claim1": "value1", "claim2": "value2" }, "scopes": [ "scope1", "scope2" ] } }, "domainName": "id.execute-api.us-east-1.amazonaws.com", "domainPrefix": "id", "http": { "method": "POST", "path": "/my/path", "protocol": "HTTP/1.1", "sourceIp": "192.0.2.1", "userAgent": "agent" }, "requestId": "id", "routeKey": "$default", "stage": "$default", "time": "12/Mar/2020:19:03:58 +0000", "timeEpoch": 1583348638390 }, "body": "Hello from Lambda", "pathParameters": { "parameter1": "value1" }, "isBase64Encoded": false, "stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" } } ``` ------ #### [ 1.0 ] ``` { "version": "1.0", "resource": "/my/path", "path": "/my/path", "httpMethod": "GET", "headers": { "header1": "value1", "header2": "value2" }, "multiValueHeaders": { "header1": [ "value1" ], "header2": [ "value1", "value2" ] }, "queryStringParameters": { "parameter1": "value1", "parameter2": "value" }, "multiValueQueryStringParameters": { "parameter1": [ "value1", "value2" ], "parameter2": [ "value" ] }, "requestContext": { "accountId": "123456789012", "apiId": "id", "authorizer": { "claims": null, "scopes": null }, "domainName": "id.execute-api.us-east-1.amazonaws.com", "domainPrefix": "id", "extendedRequestId": "request-id", "httpMethod": "GET", "identity": { "accessKey": null, "accountId": null, "caller": null, "cognitoAuthenticationProvider": null, "cognitoAuthenticationType": null, "cognitoIdentityId": null, "cognitoIdentityPoolId": null, "principalOrgId": null, "sourceIp": "192.0.2.1", "user": null, "userAgent": "user-agent", "userArn": null, "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "path": "/my/path", "protocol": "HTTP/1.1", "requestId": "id=", "requestTime": "04/Mar/2020:19:15:17 +0000", "requestTimeEpoch": 1583349317135, "resourceId": null, "resourcePath": "/my/path", "stage": "$default" }, "pathParameters": null, "stageVariables": null, "body": "Hello from Lambda!", "isBase64Encoded": false } ``` ------ ## Lambda function response format The payload format version determines the structure of the response that your Lambda function must return. ### Lambda function response for format 1.0 With the `1.0` format version, Lambda integrations must return a response in the following JSON format: **Example** ``` { "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headername": "headervalue", ... }, "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... }, "body": "..." } ``` ### Lambda function response for format 2.0 With the `2.0` format version, API Gateway can infer the response format for you. API Gateway makes the following assumptions if your Lambda function returns valid JSON and doesn't return a `statusCode`: + `isBase64Encoded` is `false`. + `statusCode` is `200`. + `content-type` is `application/json`. + `body` is the function's response. The following examples show the output of a Lambda function and API Gateway's interpretation. | Lambda function output | API Gateway interpretation | | --- | --- | | 
"Hello from Lambda!"
| 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "Hello from Lambda!",
  "headers": {
    "content-type": "application/json"
  }
}
| | 
{ "message": "Hello from Lambda!" }
| 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "{ \"message\": \"Hello from Lambda!\" }",
  "headers": {
    "content-type": "application/json"
  }
}
| To customize the response, your Lambda function should return a response with the following format. ``` { "cookies" : ["cookie1", "cookie2"], "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headername": "headervalue", ... }, "body": "Hello from Lambda!" } ``` # Create HTTP proxy integrations for HTTP APIs An HTTP proxy integration enables you to connect an API route to a publicly routable HTTP endpoint. With this integration type, API Gateway passes the entire request and response between the frontend and the backend. To create an HTTP proxy integration, provide the URL of a publicly routable HTTP endpoint. ## HTTP proxy integration with path variables You can use path variables in HTTP API routes. For example, the route `/pets/{petID}` catches requests to `/pets/6`. You can reference path variables in the integration URI to send the variable's contents to an integration. An example is `/pets/extendedpath/{petID}`. You can use greedy path variables to catch all child resources of a route. To create a greedy path variable, add `+` to the variable name—for example, `{proxy+}`. To set up a route with an HTTP proxy integration that catches all requests, create an API route with a greedy path variable (for example, `/parent/{proxy+}`). Integrate the route with an HTTP endpoint (for example, `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}`) on the `ANY` method. The greedy path variable must be at the end of the resource path. # Create AWS service integrations for HTTP APIs in API Gateway You can integrate your HTTP API with AWS services by using *first-class integrations*. A first-class integration connects an HTTP API route to an AWS service API. When a client invokes a route that's backed by a first-class integration, API Gateway invokes an AWS service API for you. For example, you can use first-class integrations to send a message to an Amazon Simple Queue Service queue, or to start an AWS Step Functions state machine. For supported service actions, see [Integration subtype reference](http-api-develop-integrations-aws-services-reference.md). ## Mapping request parameters First-class integrations have required and optional parameters. You must configure all required parameters to create an integration. You can use static values or map parameters that are dynamically evaluated at runtime. For a full list of supported integrations and parameters, see [Integration subtype reference](http-api-develop-integrations-aws-services-reference.md). The following table describes the supported mapping request parameters. | Type | Example | Notes | | --- | --- | --- | | Header value | \$1request.header.name | Header names are case-insensitive. API Gateway combines multiple header values with commas, for example "header1": "value1,value2". | | Query string value | \$1request.querystring.name | Query string names are case-sensitive. API Gateway combines multiple values with commas, for example "querystring1": "Value1,Value2". | | Path parameter | \$1request.path.name | The value of a path parameter in the request. For example if the route is /pets/\$1petId\$1, you can map the petId parameter from the request with \$1request.path.petId. | | Request body passthrough | \$1request.body | API Gateway passes the entire request body through. | | Request body | \$1request.body.name | A [JSON path expression](https://goessner.net/articles/JsonPath/index.html#e2). Recursive descent (\$1request.body..name) and filter expressions (?(expression)) aren't supported. When you specify a JSON path, API Gateway truncates the request body at 100 KB and then applies the selection expression. To send payloads larger than 100 KB, specify `$request.body`. | | Context variable | \$1context.variableName | The value of a supported [context variable](http-api-logging-variables.md). | | Stage variable | \$1stageVariables.variableName | The value of a [stage variable](http-api-stages.stage-variables.md). | | Static value | string | A constant value. | ## Create a first-class integration Before you create a first-class integration, you must create an IAM role that grants API Gateway permissions to invoke the AWS service action that you're integrating with. To learn more, see [Creating a role for an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html). To create a first-class integration, choose a supported AWS service action, such as `SQS-SendMessage`, configure the request parameters, and provide a role that grants API Gateway permissions to invoke the integrated AWS service API. Depending on the integration subtype, different request parameters are required. To learn more, see [Integration subtype reference](http-api-develop-integrations-aws-services-reference.md). The following [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) command creates an integration that sends an Amazon SQS message: ``` aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-subtype SQS-SendMessage \ --integration-type AWS_PROXY \ --payload-format-version 1.0 \ --credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \ --request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}' ``` ## Create a first-class integration using CloudFormation The following example shows an CloudFormation snippet that creates a `/{source}/{detailType}` route with a first-class integration with Amazon EventBridge. The `Source` parameter is mapped to the `{source}` path parameter, the `DetailType` is mapped to the `{DetailType}` path parameter, and the `Detail` parameter is mapped to the request body. The snippet does not show the event bus or the IAM role that grants API Gateway permissions to invoke the `PutEvents` action. ``` Route: Type: AWS::ApiGatewayV2::Route Properties: ApiId: !Ref HttpApi AuthorizationType: None RouteKey: 'POST /{source}/{detailType}' Target: !Join - / - - integrations - !Ref Integration Integration: Type: AWS::ApiGatewayV2::Integration Properties: ApiId: !Ref HttpApi IntegrationType: AWS_PROXY IntegrationSubtype: EventBridge-PutEvents CredentialsArn: !GetAtt EventBridgeRole.Arn RequestParameters: Source: $request.path.source DetailType: $request.path.detailType Detail: $request.body EventBusName: !GetAtt EventBus.Arn PayloadFormatVersion: "1.0" ``` # Integration subtype reference The following [integration subtypes](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype) are supported for HTTP APIs. **Topics** + [ ## EventBridge-PutEvents 1.0 ](#EventBridge-PutEvents) + [ ## SQS-SendMessage 1.0 ](#SQS-SendMessage) + [ ## SQS-ReceiveMessage 1.0 ](#SQS-ReceiveMessage) + [ ## SQS-DeleteMessage 1.0 ](#SQS-DeleteMessage) + [ ## SQS-PurgeQueue 1.0 ](#SQS-PurgeQueue) + [ ## AppConfig-GetConfiguration 1.0 ](#AppConfig-GetConfiguration) + [ ## Kinesis-PutRecord 1.0 ](#Kinesis-PutRecord) + [ ## StepFunctions-StartExecution 1.0 ](#StepFunctions-StartExecution) + [ ## StepFunctions-StartSyncExecution 1.0 ](#StepFunctions-StartSyncExecution) + [ ## StepFunctions-StopExecution 1.0 ](#StepFunctions-StopExecution) ## EventBridge-PutEvents 1.0 Sends custom events to Amazon EventBridge so that they can be matched to rules. | Parameter | Required | | --- | --- | | Detail | True | | DetailType | True | | Source | True | | Time | False | | EventBusName | False | | Resources | False | | Region | False | | TraceHeader | False | To learn more, see [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html) in the *Amazon EventBridge API Reference*. ## SQS-SendMessage 1.0 Delivers a message to the specified queue. | Parameter | Required | | --- | --- | | QueueUrl | True | | MessageBody | True | | DelaySeconds | False | | MessageAttributes | False | | MessageDeduplicationId | False | | MessageGroupId | False | | MessageSystemAttributes | False | | Region | False | To learn more, see [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) in the *Amazon Simple Queue Service API Reference*. ## SQS-ReceiveMessage 1.0 Retrieves one or more messages (up to 10), from the specified queue. | Parameter | Required | | --- | --- | | QueueUrl | True | | AttributeNames | False | | MaxNumberOfMessages | False | | MessageAttributeNames | False | | ReceiveRequestAttemptId | False | | VisibilityTimeout | False | | WaitTimeSeconds | False | | Region | False | To learn more, see [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) in the *Amazon Simple Queue Service API Reference*. ## SQS-DeleteMessage 1.0 Deletes the specified message from the specified queue. | Parameter | Required | | --- | --- | | ReceiptHandle | True | | QueueUrl | True | | Region | False | To learn more, see [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) in the *Amazon Simple Queue Service API Reference*. ## SQS-PurgeQueue 1.0 Deletes all messages in the specified queue. | Parameter | Required | | --- | --- | | QueueUrl | True | | Region | False | To learn more, see [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html) in the *Amazon Simple Queue Service API Reference*. ## AppConfig-GetConfiguration 1.0 Receive information about a configuration. | Parameter | Required | | --- | --- | | Application | True | | Environment | True | | Configuration | True | | ClientId | True | | ClientConfigurationVersion | False | | Region | False | To learn more, see [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html) in the *AWS AppConfig API Reference*. ## Kinesis-PutRecord 1.0 Writes a single data record into an Amazon Kinesis data stream. | Parameter | Required | | --- | --- | | StreamName | True | | Data | True | | PartitionKey | True | | SequenceNumberForOrdering | False | | ExplicitHashKey | False | | Region | False | To learn more, see [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) in the *Amazon Kinesis Data Streams API Reference*. ## StepFunctions-StartExecution 1.0 Starts a state machine execution. | Parameter | Required | | --- | --- | | StateMachineArn | True | | Name | False | | Input | False | | Region | False | To learn more, see [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) in the *AWS Step Functions API Reference*. ## StepFunctions-StartSyncExecution 1.0 Starts a synchronous state machine execution. | Parameter | Required | | --- | --- | | StateMachineArn | True | | Name | False | | Input | False | | Region | False | | TraceHeader | False | To learn more, see [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) in the *AWS Step Functions API Reference*. ## StepFunctions-StopExecution 1.0 Stops an execution. | Parameter | Required | | --- | --- | | ExecutionArn | True | | Cause | False | | Error | False | | Region | False | To learn more, see [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html) in the *AWS Step Functions API Reference*. # Create private integrations for HTTP APIs in API Gateway Private integrations enable you to create API integrations with private resources in a VPC, such as Application Load Balancers or Amazon ECS container-based applications. You can expose your resources in a VPC for access by clients outside of the VPC by using private integrations. You can control access to your API by using any of the [ authorization methods](http-api-access-control.md) that API Gateway supports. **Note** To create a private integration, you must first create a VPC link. VPC links V2 are now supported for both HTTP and REST APIs. To learn more about VPC links V2, see [Set up VPC links V2 in API Gateway](apigateway-vpc-links-v2.md). After you’ve created a VPC link V2, you can set up private integrations that connect to an Application Load Balancer, Network Load Balancer, or resources registered with an AWS Cloud Map service. ## Considerations The following considerations might impact your use of private integrations: + All resources must be owned by the same AWS account. This includes the load balancer or AWS Cloud Map service, VPC link and HTTP API. + By default, private integration traffic uses the HTTP protocol. To use HTTPS, specify a [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html). To do this using the AWS Management Console, when you create your private integration, choose **Advanced settings** and then enter a secure server name. + For private integrations, API Gateway includes the [stage](http-api-stages.md) portion of the API endpoint in the request to your backend resources. For example, a request to the `test` stage of an API includes `test/route-path` in the request to your private integration. To remove the stage name from the request to your backend resources, use [parameter mapping](http-api-parameter-mapping.md) to overwrite the request path to `$request.path`. ## Create a private integration using an Application Load Balancer or Network Load Balancer Before you create a private integration, you must create a VPC link V2. To learn more about VPC links V2, see [Set up VPC links V2 in API Gateway](apigateway-vpc-links-v2.md). To create a private integration with an Application Load Balancer or Network Load Balancer, create an HTTP proxy integration, specify the VPC link to use, and provide the listener ARN of the load balancer. The following [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) command creates a private integration that connects to a load balancer by using a VPC link: ``` aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \ --integration-method GET --connection-type VPC_LINK \ --connection-id VPC-link-ID \ --integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65 --payload-format-version 1.0 ``` ## Create a private integration using AWS Cloud Map service discovery Before you create a private integration, you must create a VPC link V2. To learn more about VPC links, see [Set up VPC links V2 in API Gateway](apigateway-vpc-links-v2.md). For integrations with AWS Cloud Map, API Gateway uses `DiscoverInstances` to identify resources. You can use query parameters to target specific resources. The registered resources' attributes must include IP addresses and ports. API Gateway distributes requests across healthy resources that are returned from `DiscoverInstances`. To learn more, see [DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html) in the AWS Cloud Map API Reference. **Note** If you use Amazon ECS to populate entries in AWS Cloud Map, you must configure your Amazon ECS task to use SRV records with Amazon ECS Service Discovery or turn on Amazon ECS Service Connect. For more information, see [Interconnecting services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/interconnecting-services.html) in the Amazon Elastic Container Service Developer Guide. To create a private integration with AWS Cloud Map, create an HTTP proxy integration, specify the VPC link to use, and provide the ARN of the AWS Cloud Map service. The following [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) command creates a private integration that uses AWS Cloud Map service discovery to identify resources: ``` aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \ --integration-method GET --connection-type VPC_LINK \ --connection-id VPC-link-ID \ --integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?stage=prod&deployment=green_deployment --payload-format-version 1.0 ```