Menu
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 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.

App user, end user, or client endpoint

An entity that uses the application built by an app developer. The entity interacts with APIs in Amazon API Gateway. 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 or 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, expressed in Velocity Template Language (VTL), to transform a request body from the frontend data format to the backend data format. Or the scripts can 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 which a payload is passed as-is from the client to the backend for a request and from the backend to the client for a response.

Model

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.