Amazon API Gateway
Developer Guide

Amazon API Gateway Concepts

API Gateway

API Gateway is an AWS service that supports the following:

  1. Creating, deploying, and managing a RESTful application programming interface (API) to expose backend HTTP endpoints, AWS Lambda functions, or other AWS services.

  2. Invoking exposed API methods through the frontend HTTP endpoints.

API Gateway API

A collection of resources and methods that are integrated with backend HTTP endpoints, Lambda functions, or other AWS services. The collection can be deployed in one or more stages. API methods are invoked through frontend HTTP endpoints that you can associate with a registered custom domain name. Permissions to invoke a method are granted using IAM roles and policies or API Gateway Lambda authorizers (formerly known as custom authorizers). An API can present a certificate to be authenticated by the backend. Typically, API resources are organized in a resource tree according to the application logic. Each API resource can expose one or more API methods that must have unique HTTP verbs supported by API Gateway.

API developer or API owner

An AWS account that owns an API Gateway deployment (for example, a service provider that also supports programmatic access.)

App developer or client developer

An app creator who may or may not have an AWS account and interacts with the API deployed by the API developer. An app developer can be represented by an API key.

API endpoints

Host names APIs in API Gateway, which are deployed to a specific region and of the {rest-api-id}.execute-api.{region} format. The following types of API endpoints are supported:

  • Edge-optimized API endpoint: The default host name of an API Gateway API that is deployed to the specified region while using a CloudFront distribution to facilitate client access typically from across AWS regions. API requests are routed to the nearest CloudFront Point of Presence (POP) which typically improves connection time for geographically diverse clients. An API is edge -optimized if you do not explicitly specify its endpoint type when creating the API.

  • Regional API endpoint: The host name of an API that is deployed to the specified region and intended to serve clients, such as EC2 instances, in the same AWS region. API requests are targeted directly to the region-specific API Gateway without going through any CloudFront distribution. For in-region requests, a regional endpoint bypasses the unnecessary round trip to a CloudFront distribution. In addition, you can apply latency-based routing on regional endpoints to deploy an API to multiple regions using the same regional API endpoint configuration, set the same custom domain name for each deployed API, and configure latency-based DNS records in Route 53 to route client requests to a region of the lowest latency.

App user, end user, or client

An app user or end user is an entity that uses a client to access an API in Amazon API Gateway. The client can be a mobile app, a web app or a desktop app, using the API Gateway REST API, the AWS CLI or SDK. An app user can be represented by an Amazon Cognito identity or a bearer token.

API key

An alphanumeric string that is generated by API Gateway on behalf of an API owner. The string can also be imported from an external source such as a CSV file. The string is used to identify an app developer of the API. An API owner can use API keys to permit or deny access of specific APIs based on the apps in use.

API deployment and stage

An API deployment is a point-in-time snapshot of the API Gateway API resources and methods. For a deployment to be accessible for a client to invoke, the deployment must be associated with one or more stages. A stage is a logical reference to a lifecycle status of your API (for example, 'dev', 'prod', 'beta', 'v2'). The identifier of an API stage consists of an API ID and stage name.

Method request

The public interface of an API method in API Gateway that defines the parameters and body that an app developer must send in the requests to access the backend through the API.

Integration request

An API Gateway internal interface that defines how API Gateway maps the parameters and body of a method request into the formats required by the backend.

Integration response

An API Gateway internal interface that defines how API Gateway maps data. The integration response includes the status codes, headers, and payload that are received from the backend into the formats defined for an app developer.

Method response

The public interface of an API that defines the status codes, headers, and body models that an app developer should expect from API Gateway.

Proxy integration

A simplified API Gateway integration configuration. You can set up a proxy integration as an HTTP proxy integration type or a Lambda proxy integration type. For the HTTP proxy integration, API Gateway passes the entire request and response between the frontend and an HTTP backend. For the Lambda proxy integration, API Gateway sends the entire request as an input to a backend Lambda function. API Gateway then transforms the Lambda function output to a frontend HTTP response. The proxy integration is most commonly used with a proxy resource, which is represented by a greedy path variable (e.g., {proxy+}) combined with a catch-all ANY method.

Mapping template

Scripts in Velocity Template Language (VTL) to transform a request body from the frontend data format to the backend data format, or to transform a response body from the backend data format to the frontend data format. Mapping templates are specified in the integration request or integration response. They can reference data made available at run time as context and stage variables. An identity transformation is referred to as a passthrough. In a passthrough, a payload is passed as-is from the client to the backend for a request. For a response, the payload is passed from the backend to the client.


Data schema specifying the data structure of a request or response payload. It is required for generating a strongly typed SDK of an API. It is also used to validate payload. A model is convenient for generating a sample mapping template to initiate creation of a production mapping template. Although useful, a model is not required for creating a mapping template.

Usage plan

A usage plan provides selected API clients with access to one or more deployed APIs. You can use a usage plan to configure throttling and quota limits, which are enforced on individual client API keys.