Amazon API Gateway Concepts
External
- https://docs.aws.amazon.com/apigateway/api-reference/resource/
- https://docs.aws.amazon.com/apigateway/api-reference/link-relation/
Internal
REST and Hypermedia Concepts
Amazon API Gateway
Amazon API Gateway is the preferred way to expose internal AWS endpoints to external clients, in form of a consistent and scalable programming REST interface (REST API). Amazon API Gateway can expose the following integration endpoints: internal HTTP(S) endpoints - representing custom services, AWS Lambda functions and other AWS services, such as Amazon Kinesis or Amazon S3. The backend endpoints are exposed by creating an API Gateway REST API (RestApi) and integrating API methods with their corresponding backend endpoints. Each of the backend endpoints specified above is associated with an integration type.
Amazon Gateway URL
The URL is determined by a protocol (HTTP(S) or WSS), a hostname, a stage name and, for REST APIs, the resource path. This URL is also known as "Invoke URL":
https://<restapi-id>.execute-api.<region>.amazonaws.com/<stage-name>/<resource-path>
Amazon Gateway API Base URL
The hostname and the stage name determine the API's base URL.
Amazon Gateway Hostname
https://<restapi-id>.execute-api.{region}.amazonaws.com
Integration
A client uses an API to access backend features by sending Method Requests. The API Gateway translates the client request, if necessary, into a format acceptable to the back end, creating an Integration Request, and forwards the Integration Request to the backend endpoint. The backend returns an Integration Response to the API Gateway, which is in turn translated by the gateway into a Method Response and sent to the client, mapping, if necessary, the backend response data to a form acceptable to the client. As an API developer, you can control the behavior of the API frontend interactions by providing (coding) appropriate method requests and responses. You can control the behavior of the API's backend interactions by setting up the integration requests and responses. These may involve data mapping between a method and its corresponding integration.
Integration Endpoints and Types
Amazon API Gateway can integrate three types of backend endpoints, and can also simulate a mock integration endpoint:
- HTTP(S) endpoints, representing client REST API services or web sites, can be integrated with HTTP proxy integration and HTTP custom integration.
- Lambda functions can be integrated with Lambda proxy integration and Lambda custom integration. The Lambda custom integration is a special case of AWS integration, where the integration endpoint corresponds to the function-invoking action of the Lambda service.
- AWS service endpoints (Amazon Kinesis or Amazon S3) can only be integrated with non-proxy (custom) integration.
- Mock backend endpoints, where API gateway serves as an integration endpoint itself. More in mock integration below.
The integration type is defined by how the API Gateway passes data to and from the integration endpoint:
Proxy Integration
In general, proxy integration implies a simple integration setup with a single HTTP endpoint or Lambda function, where the client request is passed with minimal, or no processing at all, to the backend, as input, and the backend processing result is passed directly to the client. This integration relies on direct interaction between the client and the integrated backend. Because of that, the backend can evolve without requiring updates or reconfiguration of the integration point in the API Gateway. There is no need to set the integration request or integration response. This is the preferred integration type to call Lambda functions through the API Gateway.
Custom Integration
Custom integration implies a more elaborated setup procedure. For a custom integration, both the integration request and integration response must be configured, and necessary data mappings from the method request to the integration request and from the integration response to the method response must be put in place. Among other things, custom integration allows for reuse of configured mapping templates for multiple integration endpoints that have similar requirements of the input and output data formats. Since the setup is more involved, custom integration is recommended for more advanced application scenarios.
Mock Integration
This integration type lets API Gateway return a response without sending the request further to the backend. It is useful for testing and enables collaborative development of an API, where a team can isolate their development effort by setting up simulations of the API components owned by other teams.
Configuring Integration Type
For details on how to configure a specific integration type, see below:
Integration Request
The API Gateway translates, if necessary, a client Method Request into a format acceptable to the back end and creates an Integration Request. The Integration Request is forwarded to the backend endpoint. The Integration Request is part of the REST API's interface with the backend.
Integration Response
The backend returns an Integration Response to the API Gateway, which in turn translates. it into a Method Response and sends it to the client, mapping, if necessary, the backend response data to a form acceptable to the client. The Integration Response is part of the REST API's interface with the backend. Also see IntegrationResponse below.
Mapping Template
API Gateway Resources
Amazon API Gateway Resources that Require Redeployment
Where are these resources living?
RestApi
API ID
The REST API ID is part of various API elements' ARNs.
Resource
Method
RequestValidator
MethodResponse
Integration
The integration type can be specified programmatically by setting the type property of the Integration resource as such:
- AWS: exposes an AWS service action, including Lambda, as an integration endpoint, via custom integration.
- AWS_PROXY: exposes a Lambda function (but no other AWS service) as an integration endpoint, via proxy integration.
- HTTP: exposes a HTTP(S) endpoint as an integration endpoint, via custom integration.
- HTTP_PROXY: exposes a HTTP(S) endpoint as an integration endpoin, via proxy integration.
- MOCK: sets up a mock integration endpoint.
IntegrationResponse
Also see Integration Response above.
GatewayResponse
DocumentationPart
DocumentationVersion
Model
ApiKey
See API Key below.
Authorizer
VpcLink
Amazon API Gateway Resources that Require Configuration Changes without Redeployment
Account
Deployment (API Deployment)
A Deployment resource represents a REST API deployment in Amazon API Gateway. The Deployment is like an executable of an API represented by a RestApi resource. Once an RestApi is created, it requires deployment and association with a stage to make it callable by its users. To call a deployed URL, clients submit requests against the API's URL.
Resource updates require redeploying the API, whereas configuration updates to not.
DomainName
BasePathMapping
Stage
An API stage is represented by a Stage resource and represents a named reference to a deployment, and at the same time, a snapshot of the API, including methods, integrations, models, mapping templates, Lambda authorizers, etc. An API must be deployed in a stage to be accessible to clients.
Stage Name
The stage name is part of the API URL.
Stage Operations
Usage
UsagePlan
API Gateway Link Relations
API Documentation
See DocumentationPart and DocumentationVersion above.
X-Ray Integration
API request latency issues can be troubleshot by enabling AWS X-Ray. AWS X-Ray can be used to trance API requests and downstream services.
CORS
The API Gateway console integrates the OPTIONS method to support CORS with a mock integration.
Security
Creation, Configuration and Deployment
To create, configure and deploy an API in API Gateway, the IAM user doing it must have provisioned an IAM policy that includes access permissions for manipulating the API Gateway resources and link relations. The "AmazonAPIGatewayAdministrator" AWS-managed policy grants full access to create, configure and deploy an API in API Gateway:
arn:aws:iam::aws:policy/AmazonAPIGatewayAdministrator
Attaching the preceding policy to an IAM user allows ("Effect":"Allow") the user to act with any API Gateway actions ("Action":["apigateway:*"]) on any API Gateway resources (arn:aws:apigateway:*::/*) that are associated with the user's AWS account. To refine the permissions, see Amazon API Gateway Developer Guide Page 241 "Control Access to an API with IAM Permissions".
Access
The following policy grants full access on how an API is invoked:
arn:aws:iam::aws:policy/AmazonAPIGatewayInvokeFullAccess
To refine the permissions, see Amazon API Gateway Developer Guide Page 241 "Control Access to an API with IAM Permissions".
When an API Gateway API is set up with IAM roles and policies to control client access, the client must sign API requests with Signature Version 4. Alternatively, AWS CLI or one of the AWS SDKs can be used to transparently handle request signing. For more details, see Amazon API Gateway Developer Guide Page 462 "Invoking a REST API in Amazon API Gateway".
AWS Endpoint Authentication
When API Gateway is integrated with AWS Lambda or another AWS service, such as Amazon S3 or Amazon Kinesis, the API Gateway must be enabled as a trusted entity to invoke an AWS service in the backend. This is achieved by creating an IAM role and attaching a service-specific access policy to the role. Without specifying this trust relationship, API Gateway is denied the right to call the backend on behalf of the user, even when the user has been granted permissions to access the backend directly. More details in Amazon API Gateway Developer Guide page 525.
Signature Version 4
Per-Method Authorization
API Key
See ApiKey above.