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 back-end HTTP endpoints, AWS Lambda function, or other AWS services; and

  2. Invoking exposed API methods through the front-end HTTP endpoints.

API Gateway API

A collection of resources and methods that are integrated with back-end HTTP endpoints, Lambda functions or other AWS services and can be deployed in one or more stages. API methods are invoked through front-end HTTP endpoints that can be associated with a registered custom domain names. Permissions to invoke a method can be granted using IAM roles and policies or API Gateway custom authorizers. An API can present a certificate to be authenticated by the back end. 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 who 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 that 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, which can be generated by API Gateway on behalf of an API owner or imported from an external source such as a CSV file, is used to identify an app developer of the API. An API owner can use API keys to permit or deny access of given 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 invocation by a client, it must be associated with one or more stages. A stage is a logical reference to a life-cycle status of your API (e.g., '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 back end 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 back end.

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 back end 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 front end and an HTTP back end. For the Lambda proxy integration API Gateway sends the entire request as an input to a back-end Lambda function and transforms the Lambda function output to a front-end 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 front-end data format to the back-end data format or to transform a response body from the back-end data format to the front-end data format. Mapping templates are specified in the integration request or integration response and they can reference data made available at run time in the forms of context and stage variables. An identity transformation is referred to as pass-through in which a payload is passed as-is from the client to the back end for a request and from the back end to the client for a response.

Model

Data schema specifying the data structure of a request or response payload. It is required for generating strongly typed SDK of an API, used for validating payload, and 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 with configurable throttling and quota limits enforced on individual client API keys.