# Set up an integration request in API Gateway
To set up an integration request, you perform the following required and optional tasks:
1. Choose an integration type that determines how method request data is passed to the backend.
1. For non-mock integrations, specify an HTTP method and the URI of the targeted integration endpoint, except for the `MOCK` integration.
1. For integrations with Lambda functions and other AWS service actions, set an IAM role with required permissions for API Gateway to call the backend on your behalf.
1. For non-proxy integrations, set necessary parameter mappings to map predefined method request parameters to appropriate integration request parameters.
1. For non-proxy integrations, set necessary body mappings to map the incoming method request body of a given content type according to the specified mapping template.
1. For non-proxy integrations, specify the condition under which the incoming method request data is passed through to the backend as-is.
1. Optionally, specify how to handle type conversion for a binary payload.
1. Optionally, declare a cache namespace name and cache key parameters to enable API caching.
Performing these tasks involves creating an [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) resource of API Gateway and setting appropriate property values. You can do so using the API Gateway console, AWS CLI commands, an AWS SDK, or the API Gateway REST API.
**Topics**
+ [
# Basic tasks of an API integration request
](integration-request-basic-setup.md)
+ [
# Choose an API Gateway API integration type
](api-gateway-api-integration-types.md)
+ [
# Set up a proxy integration with a proxy resource
](api-gateway-set-up-simple-proxy.md)
+ [
# Set up an API integration request using the API Gateway console
](how-to-method-settings-console.md)
# Basic tasks of an API integration request
An integration request is an HTTP request that API Gateway submits to the backend, passing along the client-submitted request data, and transforming the data, if necessary. The HTTP method (or verb) and URI of the integration request are dictated by the backend (that is, the integration endpoint). They can be the same as or different from the method request's HTTP method and URI, respectively.
For example, when a Lambda function returns a file that is fetched from Amazon S3, you can expose this operation intuitively as a `GET` method request to the client even though the corresponding integration request requires that a `POST` request be used to invoke the Lambda function. For an HTTP endpoint, it is likely that the method request and the corresponding integration request both use the same HTTP verb. However, this is not required. You can integrate the following method request:
```
GET /{var}?query=value
Host: api.domain.net
```
With the following integration request:
```
POST /
Host: service.domain.com
Content-Type: application/json
Content-Length: ...
{
path: "{var}'s value",
type: "value"
}
```
As an API developer, you can use whatever HTTP verb and URI for a method request suit your requirements. But you must follow the requirements of the integration endpoint. When the method request data differs from the integration request data, you can reconcile the difference by providing mappings from the method request data to the integration request data.
In the preceding examples, the mapping translates the path variable (`{var}`) and the query parameter (`query`) values of the `GET` method request to the values of the integration request's payload properties of `path` and `type`. Other mappable request data includes request headers and body. These are described in [Parameter mapping for REST APIs in API Gateway](rest-api-parameter-mapping.md).
When setting up the HTTP or HTTP proxy integration request, you assign the backend HTTP endpoint URL as the integration request URI value. For example, in the PetStore API, the method request to get a page of pets has the following integration request URI:
```
http://petstore-demo-endpoint.execute-api.com/petstore/pets
```
When setting up the Lambda or Lambda proxy integration, you assign the Amazon Resource Name (ARN) for invoking the Lambda function as the integration request URI value. This ARN has the following format:
```
arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations
```
The part after `arn:aws:apigateway:api-region:lambda:path/`, namely, `/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations`, is the REST API URI path of the Lambda [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) action. If you use the API Gateway console to set up the Lambda integration, API Gateway creates the ARN and assigns it to the integration URI after prompting you to choose the `lambda-function-name` from a region.
When setting up the integration request with another AWS service action, the integration request URI is also an ARN, similar to the integration with the Lambda `Invoke` action. For example, for the integration with the [GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) action of Amazon S3, the integration request URI is an ARN of the following format:
```
arn:aws:apigateway:api-region:s3:path/{bucket}
```
The integration request URI is of the path convention to specify the action, where `{bucket}` is the placeholder of a bucket name. Alternatively, an AWS service action can be referenced by its name. Using the action name, the integration request URI for the `GetBucket` action of Amazon S3 becomes the following:
```
arn:aws:apigateway:api-region:s3:action/GetBucket
```
With the action-based integration request URI, the bucket name (`{bucket}`) must be specified in the integration request body (`{ Bucket: "{bucket}" }`), following the input format of `GetBucket` action.
For AWS integrations, you must also configure [credentials](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#credentials) to allow API Gateway to call the integrated actions. You can create a new or choose an existing IAM role for API Gateway to call the action and then specify the role using its ARN. The following shows an example of this ARN:
```
arn:aws:iam::account-id:role/iam-role-name
```
This IAM role must contain a policy to allow the action to be executed. It must also have API Gateway declared (in the role's trust relationship) as a trusted entity to assume the role. Such permissions can be granted on the action itself. They are known as resource-based permissions. For the Lambda integration, you can call the Lambda's [addPermission](https://docs.aws.amazon.com/lambda/latest/dg/API_AddPermission.html) action to set the resource-based permissions and then set `credentials` to null in the API Gateway integration request.
We discussed the basic integration setup. Advanced settings involve mapping method request data to the integration request data. For more information, see [Data transformations for REST APIs in API Gateway](rest-api-data-transformations.md).
# Choose an API Gateway API integration type
You choose an API integration type according to the types of integration endpoint you work with and how you want data to pass to and from the integration endpoint. For a Lambda function, you can have the Lambda proxy integration, or the Lambda custom integration. For an HTTP endpoint, you can have the HTTP proxy integration or the HTTP custom integration. For an AWS service action, you have the AWS integration of the non-proxy type only. API Gateway also supports the mock integration, where API Gateway serves as an integration endpoint to respond to a method request.
The Lambda custom integration is a special case of the AWS integration, where the integration endpoint corresponds to the [function-invoking action ](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html)of the Lambda service.
Programmatically, you choose an integration type by setting the [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type) property on the [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) resource. For the Lambda proxy integration, the value is `AWS_PROXY`. For the Lambda custom integration and all other AWS integrations, it is `AWS`. For the HTTP proxy integration and HTTP integration, the value is `HTTP_PROXY` and `HTTP`, respectively. For the mock integration, the `type` value is `MOCK`.
The Lambda proxy integration supports a streamlined integration setup with a single Lambda function. The setup is simple and can evolve with the backend without having to tear down the existing setup. For these reasons, it is highly recommended for integration with a Lambda function.
In contrast, the Lambda custom integration allows for reuse of configured mapping templates for various integration endpoints that have similar requirements of the input and output data formats. The setup is more involved and is recommended for more advanced application scenarios.
Similarly, the HTTP proxy integration has a streamlined integration setup and can evolve with the backend without having to tear down the existing setup. The HTTP custom integration is more involved to set up, but allows for reuse of configured mapping templates for other integration endpoints.
The following list summarizes the supported integration types:
+ `AWS`: This type of integration lets an API expose AWS service actions. In `AWS` integration, you must configure both the integration request and integration response and set up necessary data mappings from the method request to the integration request, and from the integration response to the method response.
+ `AWS_PROXY`: This type of integration lets an API method be integrated with the Lambda function invocation action with a flexible, versatile, and streamlined integration setup. This integration relies on direct interactions between the client and the integrated Lambda function.
With this type of integration, also known as the Lambda proxy integration, you do not set the integration request or the integration response. API Gateway passes the incoming request from the client as the input to the backend Lambda function. The integrated Lambda function takes the [input of this format](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) and parses the input from all available sources, including request headers, URL path variables, query string parameters, and applicable body. The function returns the result following this [output format](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format).
This is the preferred integration type to call a Lambda function through API Gateway and is not applicable to any other AWS service actions, including Lambda actions other than the function-invoking action.
+ `HTTP`: This type of integration lets an API expose HTTP endpoints in the backend. With the `HTTP` integration, also known as the HTTP custom integration, you must configure both the integration request and integration response. You must set up necessary data mappings from the method request to the integration request, and from the integration response to the method response.
+ `HTTP_PROXY`: The HTTP proxy integration allows a client to access the backend HTTP endpoints with a streamlined integration setup on single API method. You do not set the integration request or the integration response. API Gateway passes the incoming request from the client to the HTTP endpoint and passes the outgoing response from the HTTP endpoint to the client.
+ `MOCK`: This type of integration lets API Gateway return a response without sending the request further to the backend. This is useful for API testing because it can be used to test the integration set up without incurring charges for using the backend and to enable collaborative development of an API.
In collaborative development, a team can isolate their development effort by setting up simulations of API components owned by other teams by using the `MOCK` integrations. It is also used to return CORS-related headers to ensure that the API method permits CORS access. In fact, the API Gateway console integrates the `OPTIONS` method to support CORS with a mock integration. [Gateway responses](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) are other examples of mock integrations.
# Set up a proxy integration with a proxy resource
To set up a proxy integration in an API Gateway API with a [proxy resource](api-gateway-method-settings-method-request.md#api-gateway-proxy-resource), you perform the following tasks:
+ Create a proxy resource with a greedy path variable of `{proxy+}`.
+ Set the `ANY` method on the proxy resource.
+ Integrate the resource and method with a backend using the HTTP or Lambda integration type.
**Note**
Greedy path variables, `ANY` methods, and proxy integration types are independent features, although they are commonly used together. You can configure a specific HTTP method on a greedy resource or apply non-proxy integration types to a proxy resource.
API Gateway enacts certain restrictions and limitations when handling methods with either a Lambda proxy integration or an HTTP proxy integration. For details, see [Amazon API Gateway important notes](api-gateway-known-issues.md).
**Note**
When using proxy integration with a passthrough, API Gateway returns the default `Content-Type:application/json` header if the content type of a payload is unspecified.
A proxy resource is most powerful when it is integrated with a backend using either HTTP proxy integration or Lambda proxy [integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
## HTTP proxy integration with a proxy resource
The HTTP proxy integration, designated by `HTTP_PROXY` in the API Gateway REST API, is for integrating a method request with a backend HTTP endpoint. With this integration type, API Gateway simply passes the entire request and response between the frontend and the backend, subject to certain [restrictions and limitations](api-gateway-known-issues.md).
**Note**
HTTP proxy integration supports multi-valued headers and query strings.
When applying the HTTP proxy integration to a proxy resource, you can set up your API to expose a portion or an entire endpoint hierarchy of the HTTP backend with a single integration setup. For example, suppose the backend of the website is organized into multiple branches of tree nodes off the root node (`/site`) as: `/site/a0/a1/.../aN`, `/site/b0/b1/.../bM`, etc. If you integrate the `ANY` method on a proxy resource of `/api/{proxy+}` with the backend endpoints with URL paths of `/site/{proxy}`, a single integration request can support any HTTP operations (GET, POST, etc.) on any of `[a0, a1, ..., aN, b0, b1, ...bM, ...]`. If you apply a proxy integration to a specific HTTP method, for example, `GET`, instead, the resulting integration request works with the specified (that is, `GET`) operations on any of those backend nodes.
## Lambda proxy integration with a proxy resource
The Lambda proxy integration, designated by `AWS_PROXY` in the API Gateway REST API, is for integrating a method request with a Lambda function in the backend. With this integration type, API Gateway applies a default mapping template to send the entire request to the Lambda function and transforms the output from the Lambda function to HTTP responses.
Similarly, you can apply the Lambda proxy integration to a proxy resource of `/api/{proxy+}` to set up a single integration to have a backend Lambda function react individually to changes in any of the API resources under `/api`.
# Set up an API integration request using the API Gateway console
An API method setup defines the method and describes its behaviors. To set up a method, you must specify a resource, including the root ("/"), on which the method is exposed, an HTTP method (`GET`, `POST`, etc.), and how it will be integrated with the targeted backend. The method request and response specify the contract with the calling app, stipulating which parameters the API can receive and what the response looks like.
The following procedures describe how to use the API Gateway console to create an integration request.
**Topics**
+ [
## Set up a Lambda integration
](#how-to-method-settings-console-lambda)
+ [
## Set up an HTTP integration
](#how-to-method-settings-console-http)
+ [
## Set up an AWS service integration
](#how-to-method-settings-console-aws)
+ [
## Set up a mock integration
](#how-to-method-settings-console-mock)
## Set up a Lambda integration
Use a Lambda function integration to integrate your API with a Lambda function. At the API level, this is an `AWS` integration type if you create a non-proxy integration, or an `AWS_PROXY` integration type if you create a proxy integration.
**To set up a Lambda integration**
1. In the **Resources** pane, choose **Create method**.
1. For **Method type**, select an HTTP method.
1. For **Integration type**, choose **Lambda function**.
1. To use a Lambda proxy integration, turn on **Lambda proxy integration**. To learn more about Lambda proxy integrations, see [Understand API Gateway Lambda proxy integration](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy).
1. For **Lambda function**, enter the name of the Lambda function.
If you are using a Lambda function in a different Region than your API, select the Region from the dropdown menu and enter the name of the Lambda function. If you are using a cross-account Lambda function, enter the function ARN.
1. To use the default timeout value of 29 seconds, keep **Default timeout** turned on. To set a custom timeout, choose **Default timeout** and enter a timeout value between `50` and `29000` milliseconds.
1. (Optional) You can configure the method request settings using the following dropdown menus. Choose **Method request settings** and configure your method request. For more information, see step 3 of [Edit an API Gateway method request in the API Gateway console](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
You can also configure your method request settings after you create your method.
1. Choose **Create method**.
## Set up an HTTP integration
Use an HTTP integration to integrate your API with an HTTP endpoint. At the API level, this is the `HTTP` integration type.
**To set up an HTTP integration**
1. In the **Resources** pane, choose **Create method**.
1. For **Method type**, select an HTTP method.
1. For **Integration type**, choose **HTTP**.
1. To use an HTTP proxy integration, turn on **HTTP proxy integration**. To learn more about HTTP proxy integrations, see [Set up HTTP proxy integrations in API Gateway](setup-http-integrations.md#api-gateway-set-up-http-proxy-integration-on-proxy-resource).
1. For **HTTP method**, choose the HTTP method type that most closely matches the method in the HTTP backend.
1. For **Endpoint URL**, enter the URL of the HTTP backend you want this method to use.
1. For **Content handling**, select a content handling behavior.
1. To use the default timeout value of 29 seconds, keep **Default timeout** turned on. To set a custom timeout, choose **Default timeout** and enter a timeout value between `50` and `29000` milliseconds.
1. (Optional) You can configure the method request settings using the following dropdown menus. Choose **Method request settings** and configure your method request. For more information, see step 3 of [Edit an API Gateway method request in the API Gateway console](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
You can also configure your method request settings after you create your method.
1. Choose **Create method**.
## Set up an AWS service integration
Use an AWS service integration to integrate your API directly with an AWS service. At the API level, this is the `AWS` integration type.
To set up an API Gateway API to do any of the following:
+ Create a new Lambda function.
+ Set a resource permission on the Lambda function.
+ Perform any other Lambda service actions.
You must choose **AWS service**.
**To set up an AWS service integration**
1. In the **Resources** pane, choose **Create method**.
1. For **Method type**, select an HTTP method.
1. For **Integration type**, choose **AWS service**.
1. For **AWS Region**, choose the AWS Region you want this method to use to call the action.
1. For **AWS service**, choose the AWS service you want this method to call.
1. For **AWS subdomain**, enter the subdomain used by the AWS service. Typically, you would leave this blank. Some AWS services can support subdomains as part of the hosts. Consult the service documentation for the availability and, if available, details.
1. For **HTTP method**, choose the HTTP method type that corresponds to the action. For HTTP method type, see the API reference documentation for the AWS service you chose for **AWS service**.
1. For **Action type**, select to either **Use action name** to use an API action or **Use path override** to use a custom resource path. For available actions and custom resource paths, see the API reference documentation for the AWS service you chose for **AWS service**.
1. Enter either an **Action name** or **Path override**.
1. For **Execution role**, enter the ARN of the IAM role that the method will use to call the action.
To create the IAM role, you can adapt the instructions in [Step 1: Create the AWS service proxy execution role](getting-started-aws-proxy.md#getting-started-aws-proxy-add-roles). Specify an access policy with the desired number of action and resource statements. For more information, see [How Amazon API Gateway works with IAM](security_iam_service-with-iam.md).
For the action and resource statement syntax, see the documentation for the AWS service you chose for **AWS service**.
For the IAM role's trust relationship, specify the following, which enables API Gateway to take action on behalf of your AWS account:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. To use the default timeout value of 29 seconds, keep **Default timeout** turned on. To set a custom timeout, choose **Default timeout** and enter a timeout value between `50` and `29000` milliseconds.
1. (Optional) You can configure the method request settings using the following dropdown menus. Choose **Method request settings** and configure your method request. For more information, see step 3 of [Edit an API Gateway method request in the API Gateway console](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
You can also configure your method request settings after you create your method.
1. Choose **Create method**.
## Set up a mock integration
Use a mock integration if you want API Gateway to act as your backend to return static responses. At the API level, this is the `MOCK` integration type. Typically, you can use the `MOCK` integration when your API is not yet final, but you want to generate API responses to unblock dependent teams for testing. For the `OPTION` method, API Gateway sets the `MOCK` integration as default to return CORS-enabling headers for the applied API resource.
**To set up a mock integration**
1. In the **Resources** pane, choose **Create method**.
1. For **Method type**, select an HTTP method.
1. For **Integration type**, choose **Mock**.
1. (Optional) You can configure the method request settings using the following dropdown menus. Choose **Method request settings** and configure your method request. For more information, see step 3 of [Edit an API Gateway method request in the API Gateway console](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console).
You can also configure your method request settings after you create your method.
1. Choose **Create method**.