Menu
Amazon API Gateway
Developer Guide

Configure Proxy Integration for a Proxy Resource

To set up a proxy resource in an API Gateway API with a proxy integration, you perform the following three 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 back end 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 Lambda proxy integration or HTTP proxy integration. For details, see Known Issues.

Note

When using proxy integration with passthrough, API Gateway will return the default Content-Type:application/json header if the content type of a payload is unspecified.

API Gateway Proxy Resource

API Gateway defines a proxy resource with the following properties:

  • A special path parameter denoted as {proxy+}. This path parameter represents any of the child resources under its parent resource of an API. In other words, /parent/{proxy+} can stand for any resource matching the path patten of /parent/*. The + symbol indicates to API Gateway to intercept all requests on the matched resource. This special path parameter is also known as a greedy path variable. The proxy variable is the greedy path variable name and can be replaced by another string in the same way you treat a regular path parameter name.

  • A special method, named ANY, used to define the same integration set up for all supported methods: DELETE, GET, HEAD, OPTIONS, PATCH, POST, and PUT.

API Gateway Proxy Integration Types

A proxy resource is most powerful when it is integrated with a back end using one of the following two proxy integration types:

  • The HTTP proxy integration, designated by HTTP_PROXY in the API Gateway REST API, is for integrating a method request with a back-end HTTP endpoint. With this integration type, API Gateway simply passes the entire request and response between the front end and the back end, subject to certain restrictions and limitations.

  • 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 back end. 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.

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 back end with a single integration set up. For example, suppose your back-end 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 back-end 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, e.g., GET, instead, the resulting integration request will work with the specified (e.g., GET) operations on any of those back-end nodes.

Similarly, you can apply the Lambda proxy integration to a proxy resource of /api/{proxy+} to set up a single integration to have a back-end Lambda function react individually to changes in any of the API resources under /api.

Set Up a Proxy Resource with the HTTP Proxy Integration

To set up a proxy resource with the HTTP proxy integration type, create an API resource with a greedy path parameter (e.g., /parent/{proxy+}) and integrate this resource with an HTTP back-end endpoint (e.g., https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}) on the ANY method. The greedy path parameter must be at the end of the resource path.

As with a non-proxy resource, you can set up a proxy resource with the HTTP proxy integration using the API Gateway console, importing a Swagger definition file, or calling the API Gateway REST API directly. For detailed instructions about using the API Gateway console to configure a proxy resource with the HTTP integration, see Create and Test an API with HTTP Proxy Integration through a Proxy Resource.

The following Swagger API definition file shows an example of an API with a proxy resource that is integrated with the PetStore website.

Copy
{ "swagger": "2.0", "info": { "version": "2016-09-12T23:19:28Z", "title": "PetStoreWithProxyResource" }, "host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com", "basePath": "/test", "schemes": [ "https" ], "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.proxy": "method.request.path.proxy" }, "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}", "passthroughBehavior": "when_no_match", "httpMethod": "ANY", "cacheNamespace": "rbftud", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "http_proxy" } } } } }

In this example, a cache key is declared on the method.request.path.proxy path parameter of the proxy resource. This is the default setting when you create the API using the API Gateway console. The API's base path (/test, corresponding to a stage) is mapped to the website's PetStore page (/petstore). The single integration request serves to mirror the entire PetStore website using the API's greedy path variable and the catch-all ANY method. The following examples illustrate this mirroring.

  • Set ANY as GET and {proxy+} as pets

    Method request initiated from the front end:

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1

    Integration request sent to the back end:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1

    The run-time instances of the ANY method and proxy resource are both valid. The call will return a 200 OK response with the payload containing the first batch of pets, as returned from the back end.

  • Set ANY as GET and {proxy+} as pets?type=dog

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1

    Integration request sent to the back end:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1

    The run-time instances of the ANY method and proxy resource are both valid. The call will return a 200 OK response with the payload containing the first batch of specified dogs, as returned from the back end.

  • Set ANY as GET and {proxy+} as pets/{petId}

    Method request initiated from the front end:

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1

    Integration request sent to the back end:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1

    The run-time instances of the ANY method and proxy resource are both valid. The call will return a 200 OK response with the payload containing the specified pet, as returned from the back end.

  • Set ANY as POST and {proxy+} as pets

    Method request initiated from the front end:

    Copy
    POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 }

    Integration request sent to the back end:

    Copy
    POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 }

    The run-time instances of the ANY method and proxy resource are both valid. The call will return a 200 OK response with the payload containing the newly created pet, as returned from the back end.

  • Set ANY as GET and {proxy+} as pets/cat

    Method request initiated from the front end:

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat

    Integration request sent to the back end:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat

    The run-time instance of the proxy resource path does not correspond to a back-end endpoint and the resulting request is invalid. As a result, a 400 Bad Request response is returned with the following error message.

    Copy
    { "errors": [ { "key": "Pet2.type", "message": "Missing required field" }, { "key": "Pet2.price", "message": "Missing required field" } ] }
  • Set ANY as GET and {proxy+} as null

    Method request initiated from the front end:

    Copy
    GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test

    Integration request sent to the back end:

    Copy
    GET http://petstore-demo-endpoint.execute-api.com/petstore

    The targeted resource is the parent of the proxy resource, but the run-time instance of the ANY method is not defined in the API on that resource. As a result, this GET request returns a 403 Forbidden response with the "Missing Authentication Token" error message as returned by API Gateway. If the API exposes the ANY or GET method on the parent resource, (/), the call will return a 404 Not Found response with the Cannot GET /petstore message as returned from the back end.

For any client request, if the targeted endpoint URL is invalid or the HTTP verb is valid but not supported, the back end returns a 404 Not Found response. For an unsupported HTTP method, a 403 Forbidden response is returned.

Set Up a Proxy Resource with the Lambda Proxy Integration

To set up a proxy resource with the Lambda proxy integration type, create an API resource with a greedy path parameter (e.g., /parent/{proxy+}) and integrate this resource with a Lambda function back end (e.g., arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource) on the ANY method. The greedy path parameter must be at the end of the API resource path. As with a non-proxy resource, you can set up the proxy resource using the API Gateway console, importing a Swagger definition file, or calling the API Gateway REST API directly.

For detailed instructions about using the API Gateway console to configure a proxy resource with the Lambda proxy integration, see Create an API with Lambda Proxy Integration through a Proxy Resource.

The following Swagger API definition file shows an example of an API with a proxy resource that is integrated with the SimpleLambda4ProxyResource Lambda function.

Copy
{ "swagger": "2.0", "info": { "version": "2016-09-12T17:50:37Z", "title": "ProxyIntegrationWithLambda" }, "host": "gy415nuibc.execute-api.us-east-1.amazonaws.com", "basePath": "/testStage", "schemes": [ "https" ], "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations", "passthroughBehavior": "when_no_match", "httpMethod": "POST", "cacheNamespace": "roq9wj", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "aws_proxy" } } } } }

With the Lambda proxy integration, at run time, API Gateway maps an incoming request into the input event parameter of the Lambda function. The input includes the request method, path, headers, any query parameters, any payload, associated context, and any defined stage variables. The input format is explained in Input Format of a Lambda Function for Proxy Integration . For API Gateway to map the Lambda output to HTTP responses successfully, the Lambda function must output the result in the format explained in Output Format of a Lambda Function for Proxy Integration.

With the Lambda proxy integration of a proxy resource through the ANY method, the single back-end Lambda function serves as the event handler for all requests through the proxy resource. For example, to log traffic patterns, you can have a mobile device send its location in terms of state, city, street, and building by submitting a request with /state/city/street/house in the URL path for the proxy resource. The back-end Lambda function can then parse the URL path and insert the location tuples into a DynamoDB table.

Input Format of a Lambda Function for Proxy Integration

With the Lambda proxy integration, API Gateway maps the entire client request to the input event parameter of the back-end Lambda function as follows:

Copy
{ "resource": "Resource path", "path": "Path parameter", "httpMethod": "Incoming request's method name" "headers": {Incoming request headers} "queryStringParameters": {query string parameters } "pathParameters": {path parameters} "stageVariables": {Applicable stage variables} "requestContext": {Request context, including authorizer-returned key-value pairs} "body": "A JSON string of the request payload." "isBase64Encoded": "A boolean flag to indicate if the applicable request payload is Base64-encode" }

Let's illustrate this using the following POST request shows an API deployed to testStage with a stage variable of stageVariableName=stageVariableValue:

Copy
POST /testStage/hello/world?name=me HTTP/1.1 Host: gy415nuibc.execute-api.us-east-1.amazonaws.com Content-Type: application/json headerName: headerValue { "a": 1 }

The above request produces the following response payload containing the output returned from the back-end Lambda function, where input was set to the event parameter to the Lambda function.

Copy
{ "message": "Hello me!", "input": { "resource": "/{proxy+}", "path": "/hello/world", "httpMethod": "POST", "headers": { "Accept": "*/*", "Accept-Encoding": "gzip, deflate", "cache-control": "no-cache", "CloudFront-Forwarded-Proto": "https", "CloudFront-Is-Desktop-Viewer": "true", "CloudFront-Is-Mobile-Viewer": "false", "CloudFront-Is-SmartTV-Viewer": "false", "CloudFront-Is-Tablet-Viewer": "false", "CloudFront-Viewer-Country": "US", "Content-Type": "application/json", "headerName": "headerValue", "Host": "gy415nuibc.execute-api.us-east-1.amazonaws.com", "Postman-Token": "9f583ef0-ed83-4a38-aef3-eb9ce3f7a57f", "User-Agent": "PostmanRuntime/2.4.5", "Via": "1.1 d98420743a69852491bbdea73f7680bd.cloudfront.net (CloudFront)", "X-Amz-Cf-Id": "pn-PWIJc6thYnZm5P0NMgOUglL1DYtl0gdeJky8tqsg8iS_sgsKD1A==", "X-Forwarded-For": "54.240.196.186, 54.182.214.83", "X-Forwarded-Port": "443", "X-Forwarded-Proto": "https" }, "queryStringParameters": { "name": "me" }, "pathParameters": { "proxy": "hello/world" }, "stageVariables": { "stageVariableName": "stageVariableValue" }, "requestContext": { "accountId": "12345678912", "resourceId": "roq9wj", "stage": "testStage", "requestId": "deef4878-7910-11e6-8f14-25afc3e9ae33", "identity": { "cognitoIdentityPoolId": null, "accountId": null, "cognitoIdentityId": null, "caller": null, "apiKey": null, "sourceIp": "192.168.196.186", "cognitoAuthenticationType": null, "cognitoAuthenticationProvider": null, "userArn": null, "userAgent": "PostmanRuntime/2.4.5", "user": null }, "resourcePath": "/{proxy+}", "httpMethod": "POST", "apiId": "gy415nuibc" }, "body": "{\r\n\t\"a\": 1\r\n}", "isBase64Encoded": false } }

Note

API Gateway enacts certain restrictions and limitations when handling methods with either Lambda proxy integration or HTTP proxy integration. For details, see Known Issues.

Output Format of a Lambda Function for Proxy Integration

With the Lambda proxy integration, API Gateway requires the back-end Lambda function to return output according to the following JSON format:

Copy
{ "statusCode": httpStatusCode, "headers": { "headerName": "headerValue", ... }, "body": "..." }

A Lambda function in Node.js can supply a JSON object of this format as the input to the context.succeed( {...} ); function call. If the function output is of a different format, API Gateway will return a 502 Bad Gateway error response.