You can create a web API with an HTTP endpoint for your Lambda function by using Amazon API Gateway. API Gateway provides tools for creating and documenting web APIs that route HTTP requests to Lambda functions. You can secure access to your API with authentication and authorization controls. Your APIs can serve traffic over the internet or can be accessible only within your VPC. Show Resources
in your API define one or more methods, such as GET or POST. Methods have an integration that routes requests to a Lambda function or another integration type. You can define each resource and method individually, or use special resource and method types to match all requests that fit a pattern. A proxy resource catches all paths beneath a resource. The Sections
Adding an endpoint to your Lambda functionTo add a public endpoint to your Lambda function
Proxy integrationAPI Gateway APIs are comprised of stages, resources, methods, and integrations. The stage and resource determine the path of the endpoint: API path format
A Lambda integration maps a path and HTTP method combination to a Lambda function. You can configure API Gateway to pass the body of the HTTP request as-is (custom integration), or to encapsulate the request body in a document that includes all of the request information including headers, resource, path, and method. Event formatAmazon API Gateway invokes your function synchronously with an event that contains a JSON representation of the HTTP request. For a custom integration, the event is the body of the request. For a proxy integration, the event has a defined structure. The following example shows a proxy event from an API Gateway REST API. Example event.json API Gateway proxy event (REST API)
Response formatAPI Gateway waits for a response from your function and relays the result to the caller. For a custom integration, you define an integration response and a method response to convert the output from the function to an HTTP response. For a proxy integration, the function must respond with a representation of the response in a specific format. The following example shows a response object from a Node.js function. The response object represents a successful HTTP response that contains a JSON document. Example index.js – Proxy integration response object (Node.js)
The Lambda runtime serializes the response object into JSON and sends it to the API. The API parses the response and uses it to create an HTTP response, which it then sends to the client that made the original request. Example HTTP response
PermissionsAmazon API Gateway gets permission to invoke your function from the function's resource-based policy. You can grant invoke permission to an entire API, or grant limited access to a stage, resource, or method. When you add an API to your function by using the Lambda console, using the API Gateway console, or in an AWS SAM template, the function's resource-based policy is updated automatically. The following is an example function policy. Example function policy
You can manage function policy permissions manually with the following API operations:
To grant invocation permission to an existing API, use the
You should see the following output:
If your function and API are in different regions, the region identifier in the source ARN must match the region of the function, not the region of the API. When API Gateway invokes a function, it uses a resource ARN that is based on the ARN of the API, but modified to match the function's region. The source ARN in this example grants permission to an integration on the GET method of the root resource in the default stage of an API, with ID
Resource patterns
For details on viewing the policy and removing statements, see Cleaning up resource-based policies. Handling errors with an API Gateway APIAPI Gateway treats all invocation and function errors as internal errors. If the Lambda API rejects the invocation request, API Gateway returns a 500 error code. If the function runs but returns an error, or returns a response in the
wrong format, API Gateway returns a 502. In both cases, the body of the response from API Gateway is API Gateway does not retry any Lambda invocations. If Lambda returns an error, API Gateway returns an error response to the client. The following example shows an X-Ray trace map for a request that resulted in a function error and a 502 from API Gateway. The client receives the generic error message. To customize the error response, you must catch errors in your code and format a response in the required format. Example index.js – Error formatting
API Gateway converts this response into an HTTP error with a custom status code and body. In the trace map, the function node is green because it handled the error. Choosing an API typeAPI Gateway supports three types of APIs that invoke Lambda functions:
HTTP APIs and REST APIs are both RESTful APIs that process HTTP requests and return responses. HTTP APIs are newer and are built with the API Gateway version 2 API. The following features are new for HTTP APIs: HTTP API features
REST APIs are the classic RESTful APIs that API Gateway has supported since launch. REST APIs currently have more customization, integration, and management features. REST API features
For a detailed comparison, see Choosing between HTTP APIs and REST APIs in the API Gateway Developer Guide. WebSocket APIs also use the API Gateway version 2 API and support a similar feature set. Use a WebSocket API for applications that benefit from a persistent connection between the client and API. WebSocket APIs provide full-duplex communication, which means that both the client and the API can send messages continuously without waiting for a response. HTTP APIs support a simplified event format (version 2.0). The following example shows an event from an HTTP API. Example event-v2.json – API Gateway proxy event (HTTP API)
For more information, see AWS Lambda integrations in the API Gateway Developer Guide. Sample applicationsThe GitHub repository for this guide provides the following sample application for API Gateway.
Lambda also provides blueprints and templates that you can use to create an API Gateway application in the Lambda console. |