Menu
Amazon API Gateway
Developer Guide

Overview of the API Gateway Lambda Proxy Integration

The Lambda proxy integration of API Gateway is a simple, powerful, and nimble mechanism to build an API with a setup of a single API method. The Lambda proxy integration allows the client to call a single Lambda function in the backend. The function accesses many resources or features of other AWS services, including calling other Lambda functions.

With the Lambda proxy integration, when a client submits an API request, API Gateway passes to the integrated Lambda function the raw request as-is. This request data includes the request headers, query string parameters, URL path variables, payload, and API configuration data. The configuration data can include current deployment stage name, stage variables, user identity, or authorization context (if any). The backend Lambda function parses the incoming request data to determine the response that it returns. For API Gateway to pass the Lambda output as the API response to the client, the Lambda function must return the result in this format.

Because API Gateway doesn't intervene very much between the client and the backend Lambda function for the Lambda proxy integration, the client and the integrated Lambda function can adapt to changes in each other without breaking the existing integration setup of the API. To enable this, the client must follow application protocols enacted by the backend Lambda function.

You can set up a Lambda proxy integration for any API method. But a Lambda proxy integration is more potent when it is configured for an API method involving a generic proxy resource. The generic proxy resource can be denoted by a special templated path variable of {proxy+}, the catch-all ANY method placeholder, or both. The client can pass the input to the backend Lambda function in the incoming request as request parameters or applicable payload. The request parameters include headers, URL path variables, query string parameters, and the applicable payload. The integrated Lambda function verifies all of the input sources before processing the request and responding to the client with meaningful error messages if any of the required input is missing.

When calling an API method integrated with the generic HTTP method of ANY and the generic resource of {proxy+}, the client submits a request with a particular HTTP method in place of ANY. The client also specifies a particular URL path instead of {proxy+}, and includes any required headers, query string parameters, or an applicable payload.

The following list summarizes runtime behaviors of different API methods with the Lambda proxy integration:

  • ANY /{proxy+}: The client must choose a particular HTTP method, must set a particular resource path hierarchy, and can set any headers, query string parameters, and applicable payload to pass the data as input to the integrated Lambda function.

  • ANY /res: The client must choose a particular HTTP method and can set any headers, query string parameters, and applicable payload to pass the data as input to the integrated Lambda function.

  • GET|POST|PUT|... /{proxy+}: The client can set a particular resource path hierarchy, any headers, query string parameters, and applicable payload to pass the data as input to the integrated Lambda function.

  • GET|POST|PUT|... /res/{path}/...: The client must choose a particular path segment (for the {path} variable) and can set any request headers, query string parameters, and applicable payload to pass input data to the integrated Lambda function.

  • GET|POST|PUT|... /res: The client can choose any request headers, query string parameters, and applicable payload to pass input data to the integrated Lambda function.

Both the proxy resource of {proxy+} and the custom resource of {custom} are expressed as templated path variables. However {proxy+} can refer to any resource along a path hierarchy, while {custom} refers to a particular path segment only. For example, a grocery store might organize its online product inventory by department names, produce categories, and product types. The grocery store's website can then represent available products by the following templated path variables of custom resources: /{department}/{produce-category}/{product-type}. For example, apples are represented by /produce/fruit/apple and carrots by /produce/vegetables/carrot. It can also use /{proxy+} to represent any department, any produce category, or any product type that a customer can search for while shopping in the online store. For example, /{proxy+} can refer to any of the following items:

  • /produce

  • /produce/fruit

  • /produce/vegetables/carrot

To let customers search for any available product, its produce category, and the associated store department, you can expose a single method of GET /{proxy+} with read-only permissions. Similarly, to allow a supervisor to update the produce department's inventory, you can set up another single method of PUT /produce/{proxy+} with read/write permissions. To allow a cashier to update the running total of a vegetable, you can set up a POST /produce/vegetables/{proxy+} method with read/write permissions. To let a store manager perform any possible action on any available product, the online store developer can expose the ANY /{proxy+} method with read/write permissions. In any case, at run time, the customer or the employee must select a particular product of a given type in a chosen department, a specific produce category in a chosen department, or a specific department.

For more information about setting up the API Gateway proxy integrations, see Set up API Gateway Proxy Integration.

The proxy integration requires that the client have more detailed knowledge of the backend requirements. Therefore, to ensure optimal app performance and user experience, the backend developer must communicate clearly to the client developer the requirements of the backend, and provide a robust error feedback mechanism when the requirements are not met.