Develop REST APIs in API Gateway
In Amazon API Gateway, you build a REST API as a collection of programmable entities known as API Gateway resources. For example, you use a RestApi resource to represent an API that can contain a collection of Resource entities.
Each Resource entity can have one or more Method
resources. A Method is an incoming request submitted by the client and can contain the following
request parameters: a path parameter, a header, or a query string parameter. In addition, depending on the HTTP
method, the request can contain a body. Your method defines how the client to accesses the exposed
Resource. To integrate the Method with a backend endpoint, also known as the integration
endpoint, you create an Integration resource. This forwards
the incoming request to a specified integration endpoint URI. If necessary, you can transform request parameters or
the request body to meet the backend requirements, or you can create a proxy integration, where API Gateway sends the
entire request in a standardized format to the integration endpoint URI and then directly
sends the response to the client.
For responses, you can create a MethodResponse resource to represent a response received by the client and you create an IntegrationResponse resource to represent the response that is returned by the backend. Use an integration response to transform the backend response data before returning the data to the client or to pass the backend response as-is to the client.
Example resource for a REST API
The following diagram shows how API Gateway implements this request/response model for an HTTP
proxy and an HTTP non-proxy integration for the GET /pets resource. The client sends the
x-version:beta header to API Gateway and API Gateway sends the 204 status code to the client.
In the non-proxy integration, API Gateway performs data transformations to meet the backend requirements, by modifying the integration request and integration response. In a non-proxy integration, you can access the body in the method request but you transform it in the integration request. When the integration endpoint returns a response with a body, you access and transform it in the integration response. You can't modify the body in the method response.
In the proxy integration, the integration endpoint modifies the request and response. API Gateway doesn't modify the integration request or integration response, and sends the incoming request to the backend as-is.
Regardless of the integration type, the client sent a request to API Gateway and API Gateway responded synchronously.
The following example execution logs show what API Gateway would log in the previous example. For clarity, some values and initial logs have been removed:
To import a similar API and test it in the AWS Management Console, see the example API.
Additional REST API features for development
API Gateway supports additional features for the development of your REST API. For example, to help your customers understand your API, you can provide documentation for the API. To enable this, add a DocumentationPart resource for a supported API entity.
To control how clients call an API, use IAM permissions, a Lambda authorizer, or an Amazon Cognito user pool. To meter the use of your API, set up usage plans to throttle API requests. You can enable these when creating or updating your API.
The following diagram shows the features available for REST API development and where in the request/response model these features are configured.
For an introduction on how to create an API, see Tutorial: Create a REST API with a Lambda proxy integration. To learn more information about the capabilities of API Gateway that you might use while developing a REST API, see the following topics. These topics contain conceptual information and procedures that you can perform using the API Gateway console, the API Gateway REST API, the AWS CLI, or one of the AWS SDKs.
Topics
