# Create AWS service integrations for HTTP APIs in API Gateway
<a name="http-api-develop-integrations-aws-services"></a>

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
<a name="http-api-develop-integrations-aws-services-parameter-mapping"></a>

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
<a name="http-api-develop-integrations-aws-services-example"></a>

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
<a name="http-api-develop-integrations-aws-services-example-cfn"></a>

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
<a name="http-api-develop-integrations-aws-services-reference"></a>

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
<a name="EventBridge-PutEvents"></a>

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
<a name="SQS-SendMessage"></a>

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
<a name="SQS-ReceiveMessage"></a>

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
<a name="SQS-DeleteMessage"></a>

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
<a name="SQS-PurgeQueue"></a>

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
<a name="AppConfig-GetConfiguration"></a>

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
<a name="Kinesis-PutRecord"></a>

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
<a name="StepFunctions-StartExecution"></a>

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
<a name="StepFunctions-StartSyncExecution"></a>

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
<a name="StepFunctions-StopExecution"></a>

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*.