Amazon API Gateway

API Gateway is a fully managed service that makes it easy for developers to publish, maintain, monitor, and secure APIs at any scale.

API Gateway supports the following:

  • Creating, deploying, and managing a REST application programming interface (API) to expose backend HTTP endpoints, AWS Lambda functions, or other AWS services.
  • Creating, deploying, and managing a WebSocket API to expose AWS Lambda functions or other AWS services.
  • Invoking exposed API methods through the frontend HTTP and WebSocket endpoints.

Together with Lambda, API Gateway forms the app-facing part of the AWS serverless infrastructure.

Back-end services include Amazon EC2, AWS Lambda or any web application (public or private endpoints).

API Gateway handles all the tasks involved in accepting and processing up to hundreds of thousands of concurrent API calls.

API calls include traffic management, authorization and access control, monitoring, and API version management.

API Gateway provides a REST API that uses JSON.

API Gateway exposes HTTPS endpoints to define a RESTful API.

All the APIs created with Amazon API Gateway expose HTTPS endpoints only (does not support unencrypted endpoints).

An API can present a certificate to be authenticated by the back end.

Can send each API endpoint to a different target.

CloudFront is used as the public endpoint for API Gateway.

Using CloudFront behind the scenes, custom domains, and SNI are supported.

Supports API keys and Usage Plans for user identification, throttling or quota management.

Permissions to invoke a method are granted using IAM roles and policies or API Gateway custom authorizers.

By default API Gateway assigns an internal domain that automatically uses the API Gateway certificates.

When configuring your APIs to run under a custom domain name you can provide your own certificate.

Amazon API Gateway Features

The following table describes some of the core features of Amazon API Gateway.

API Gateway FeatureBenefit
Support for RESTful APIs and WebSocket APIsWith API Gateway, you can create RESTful APIs using either HTTP APIs or REST APIs
Private integrations with AWS ELB & AWS Cloud MapWith API Gateway, you can route requests to private resources in your VPC. Using HTTP APIs, you can build APIs for services behind private ALBs, private NLBs, and IP-based services registered in AWS Cloud Map, such as ECS tasks.
MeteringDefine plans that meter and restrict third-party developer access to APIs.
SecurityAPI Gateway provides multiple tools to authorize access to APIs and control service operation access.
ResiliencyManage traffic with throttling so that backend operations can withstand traffic spikes.
Operations MonitoringAPI Gateway provides a metrics dashboard to monitor calls to services.
Lifecycle ManagementOperate multiple API versions and multiple stages for each version simultaneously so that existing applications can continue to call previous versions after new API versions are published.
AWS AuthorizationSupport for signature version 4 for REST APIs and WebSocket APIs, IAM access policies, and authorization with bearer tokens (e.g., JWT, SAML) using Lambda functions.


An API endpoint type is a hostname for an API in API Gateway that is deployed to a specific region.

The hostname is of the form {api-id}.execute-api.{region}

The API endpoint type can be edge-optimized, regional, or private, depending on where most of your API traffic originates from.

Edge-Optimized Endpoint

  • An edge-optimized API endpoint is best for geographically distributed clients. API requests are routed to the nearest CloudFront Point of Presence (POP). This is the default endpoint type for API Gateway REST APIs.
  • Edge-optimized APIs capitalize the names of HTTP headers (for example, Cookie).
  • CloudFront sorts HTTP cookies in natural order by cookie name before forwarding the request to your origin. For more information about the way CloudFront processes cookies, see Caching Content Based on Cookies.
  • Any custom domain name that you use for an edge-optimized API applies across all regions.

Regional Endpoint

  • A regional API endpoint is intended for clients in the same region.
  • When a client running on an EC2 instance calls an API in the same region, or when an API is intended to serve a small number of clients with high demands, a regional API reduces connection overhead.
  • For a regional API, any custom domain name that you use is specific to the region where the API is deployed.
  • If you deploy a regional API in multiple regions, it can have the same custom domain name in all regions.
  • You can use custom domains together with Amazon Route 53 to perform tasks such as latency-based routing.
  • Regional API endpoints pass all header names through as-is.

Private Endpoint

  • A private API endpoint is an API endpoint that can only be accessed from your Amazon Virtual Private Cloud (VPC) using an interface VPC endpoint, which is an endpoint network interface (ENI) that you create in your VPC.
  • Private API endpoints pass all header names through as-is.

The following diagram depicts the three different Amazon API Gateway endpoint types:

Amazon API Gateway API’s


  • A collection of HTTP resources and methods that are integrated with backend HTTP endpoints, Lambda functions, or other AWS services.
  • This collection can be deployed in one or more stages.
  • 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 have unique HTTP verbs supported by API Gateway.

The following diagram depicts the structure of an API:

API Gateway WebSocket API

  • A collection of WebSocket routes and route keys 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 WebSocket connections that you can associate with a registered custom domain name.


API Gateway Methods are HTTP methods associated with an API Gateway resource.

Each resource URL can have HTTP methods such as: GET, PUT, POST and DELETE.

AWS also offers the “ANY” method as a catch-all.


Deployments are a snapshot of the APIs resources and methods.

Deployments must be created and associated with a stage for anyone to access the API.

Stages and Stage variables

A stage is a logical reference to a lifecycle state of your REST or WebSocket API (for example, ‘dev’, ‘prod’, ‘beta’, ‘v2’).

API stages are identified by API ID and stage name.

Stage variables are like environment variables for API Gateway.

Stage variables can be used in:

  • Lambda function ARN.
  • HTTP endpoint.
  • Parameter mapping templates.

Use cases for stage variables:

  • Configure HTTP endpoints your stages talk to (dev, test, prod etc.).
  • Pass configuration parameters to AWS Lambda through mapping templates.

Stage variables are passed to the “context” object in Lambda.

Stage variables are used with Lambda aliases.

You can create a stage variable to indicate the corresponding Lambda alias.

You can create canary deployments for any stage – choose the % of traffic the canary channel receives.

Mapping templates

Mapping templates can be used to modify request / responses.

Rename parameters.

Modify body content.

Add headers.

Map JSON to XML for sending to backend or back to client.

Uses Velocity Template Language (VTL).

Filter output results (remove unnecessary data).


You can add caching to API calls by provisioning an Amazon API Gateway cache and specifying its size in gigabytes.

Caching allows you to cache the endpoint’s response.

Caching can reduce the number of calls to the backend and improve the latency of requests to the API.

API Gateway caches responses for a specific amount of time (time to live or TTL).

The default TTL is 300 seconds (min 0, max 3600).

Caches are defined per stage.

You can encrypt caches.

The cache capacity is between 0.5GB to 237GB.

It is possible to override cache settings for specific methods.

You can flush the entire cache (invalidate it) immediately if required.

Clients can invalidate the cache with the header: Cache-Control: max-age=0 .

API throttling

API Gateway sets a limit on a steady-state rate and a burst of request submissions against all APIs in your account.


  • By default API Gateway limits the steady-state request rate to 10,000 requests per second.
  • The maximum concurrent requests is 5,000 requests across all APIs within an AWS account.
  • If you go over 10,000 requests per second or 5,000 concurrent requests you will receive a 429 Too Many Requests error response.

Upon catching such exceptions, the client can resubmit the failed requests in a way that is rate-limiting, while complying with the API Gateway throttling limits.

Amazon API Gateway provides two basic types of throttling-related settings:

  • Server-side throttling limits are applied across all clients. These limit settings exist to prevent your API—and your account—from being overwhelmed by too many requests.
  • Per-client throttling limits are applied to clients that use API keys associated with your usage policy as a client identifier.

API Gateway throttling-related settings are applied in the following order:

  1. Per-client per-method throttling limits that you set for an API stage in a usage plan.
  2. Per-client throttling limits that you set in a usage plan.
  3. Default per-method limits and individual per-method limits that you set in API stage settings.
  4. Account-level throttling.

Integrations and Method Requests / Responses

A method represents a client-facing interface by which the client calls the API to access back-end resources.

A Method resource is integrated with an Integration resource.

API methods are integrated with backend endpoints using API integrations.

Backend endpoints are known as “integration endpoints”.

Integration request

The internal interface of a WebSocket API route or REST API method in API Gateway, in which you map the body of a route request or the parameters and body of a method request to the formats required by the backend.

Integration response

The internal interface of a WebSocket API route or REST API method in API Gateway, in which you map the status codes, headers, and payload that are received from the backend to the response format that is returned to a client app.

Method request

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

Method response

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

Mapping template

A script in Velocity Template Language (VTL) that transforms a request body from the frontend data format to the backend data format, or that transforms a response body from the backend data format to the frontend data format.

Mapping templates can be specified in the integration request or in the integration response. They can reference data made available at run time as context and stage variables.

The mapping can be as simple as an identity transform that passes the headers or body through the integration as-is from the client to the backend for a request.

The same is true for a response, in which the payload is passed from the backend to the client.

Integration Type

You choose an API integration type according to the types of integration endpoint you work with and how you want data to pass to and from the integration endpoint.

For a Lambda function, you can have the Lambda proxy integration, or the Lambda custom integration.

For an HTTP endpoint, you can have the HTTP proxy integration or the HTTP custom integration.

For an AWS service action, you have the AWS integration of the non-proxy type only. API Gateway also supports the mock integration, where API Gateway serves as an integration endpoint to respond to a method request.

The Lambda custom integration is a special case of the AWS integration, where the integration endpoint corresponds to the function-invoking action of the Lambda service.

Programmatically, you choose an integration type by setting the type property on the Integration resource.

For the Lambda proxy integration, the value is AWS_PROXY.

For the Lambda custom integration and all other AWS integrations, it is AWS.

For the HTTP proxy integration and HTTP integration, the value is HTTP_PROXY and HTTP, respectively.

For the mock integration, the type value is MOCK.

The following list summarizes the supported integration types:

AWS Integration

This type of integration lets an API expose AWS service actions.

In AWS integration, you must configure both the integration request and integration response and set up necessary data mappings from the method request to the integration request, and from the integration response to the method response.

AWS_PROXY Integration

This type of integration lets an API method be integrated with the Lambda function invocation action with a flexible, versatile, and streamlined integration setup.

This integration relies on direct interactions between the client and the integrated Lambda function.

With this type of integration, also known as the Lambda proxy integration, you do not set the integration request or the integration response.

API Gateway passes the incoming request from the client as the input to the backend Lambda function.

The integrated Lambda function takes the input of this format and parses the input from all available sources, including request headers, URL path variables, query string parameters, and applicable body.

The function returns the result following this output format.

This is the preferred integration type to call a Lambda function through API Gateway and is not applicable to any other AWS service actions, including Lambda actions other than the function-invoking action.

HTTP Integration

This type of integration lets an API expose HTTP endpoints in the backend.

With the HTTP integration, also known as the HTTP custom integration, you must configure both the integration request and integration response.

You must set up necessary data mappings from the method request to the integration request, and from the integration response to the method response.

HTTP_PROXY Integration

The HTTP proxy integration allows a client to access the backend HTTP endpoints with a streamlined integration setup on single API method.

You do not set the integration request or the integration response.

API Gateway passes the incoming request from the client to the HTTP endpoint and passes the outgoing response from the HTTP endpoint to the client.

MOCK Integration

This type of integration lets API Gateway return a response without sending the request further to the backend.

This is useful for API testing because it can be used to test the integration set up without incurring charges for using the backend and to enable collaborative development of an API.

In collaborative development, a team can isolate their development effort by setting up simulations of API components owned by other teams by using the MOCK integrations.

It is also used to return CORS-related headers to ensure that the API method permits CORS access.

In fact, the API Gateway console integrates the OPTIONS method to support CORS with a mock integration.

Gateway responses are other examples of mock integrations.

Usage plans and API keys

A usage plan specifies who can access one or more deployed API stages and methods — and how much and how fast they can access them.

You can use a usage plan to configure throttling and quota limits, which are enforced on individual client API keys.

The plan uses API keys to identify API clients and meters access to the associated API stages for each key.

It also lets you configure throttling limits and quota limits that are enforced on individual client API keys.

API keys are alphanumeric string values that you distribute to app developer customers to grant access to your API.

You can use API keys together with usage plans or Lambda authorizers to control access to your APIs.

API Gateway can generate API keys on your behalf, or you can import them from a CSV file.

You can generate an API key in API Gateway or import it into API Gateway from an external source.

Same origin policy

Used to prevent cross-site scripting attacks.

Web browser permits scripts in a first web page to access data in a second web page but only if the web pages have the same origin.

This is enforced by web browsers.

Cross-origin resource sharing (CORS)

Can enable Cross Origin Resource Sharing (CORS) for multiple domain use with JavaScript/AJAX.

CORS is one way that the server at the other end (not the client code in the browser) can relax the same-origin policy.

CORS allows restricted resources (e.g. fonts) on a web page to be requested from another domain outside the domain from which the first resource was shared.

Using CORS:

  • Can enable CORS on API Gateway if using JavaScript / AJAX.
  • Can be used to enable requests from domains other than the APIs domain.
  • Allows the sharing of resources between different domains.
  • The method (GET, PUT, POST etc.) for which you will enable CORS must be available in the API Gateway API before you enable CORS.
  • If CORS is not enabled and an API resource received requests from another domain the request will be blocked.
  • Enable CORS on the API resources using the selected methods under the API Gateway.

Identity and Access Management

There are several mechanisms for controlling and managing access to an API.

These mechanisms include:

  • Resource-based policies.
  • Standard IAM Roles and Policies (identity-based policies).
  • IAM Tags.
  • Endpoint policies for interface VPC endpoints.
  • Lambda authorizers.
  • Amazon Cognito user pools.

IAM Resource-Based Policies

Amazon API Gateway resource policies are JSON policy documents that you attach to an API to control whether a specified principal (typically an IAM user or role) can invoke the API.

You can use API Gateway resource policies to allow your API to be securely invoked by:

  • Users from a specified AWS account.
  • Specified source IP address ranges or CIDR blocks.
  • Specified virtual private clouds (VPCs) or VPC endpoints (in any account).
  • You can use resource policies for all API endpoint types in API Gateway: private, edge-optimized, and Regional.

IAM Identity-Based Policies

You need to create IAM policies and attach to users / roles.

API Gateway verifies IAM permissions passed by the calling application.

Leverages sigv4 capability where IAM credentials are passed in headers.

Handles authentication and authorization.

Great for user / roles within your AWS account.

Lambda Authorizer

Use AWS Lambda to validate the token in the header being passed.

Option to cache the result of the authentication.

Lambda must return an IAM policy for the user.

You pay per Lambda invocation.

Handles authentication and authorization.

Good for using OAuth, SAML or 3rd party authentication.

Cognito User Pools

A user pool is a user directory in Amazon Cognito.

With a user pool, users can sign in to a web or mobile app through Amazon Cognito.

Users can also sign in through social identity providers like Google, Facebook, Amazon, or Apple, and through SAML identity providers.

Whether your users sign in directly or through a third party, all members of the user pool have a directory profile that you can access through a Software Development Kit (SDK).

User pools provide:

  • Sign-up and sign-in services.
  • A built-in, customizable web UI to sign in users.
  • Social sign-in with Facebook, Google, Login with Amazon, and Sign in with Apple, as well as sign-in with SAML identity providers from your user pool.
  • User directory management and user profiles.
  • Security features such as multi-factor authentication (MFA).

Additional Features and Benefits

API Gateway provides several features that assist with creating and managing APIs:

  • Metering – Define plans that meter and restrict third-party developer access to APIs.
  • Security – API Gateway provides multiple tools to authorize access to APIs and control service operation access.
  • Resiliency – Manage traffic with throttling so that backend operations can withstand traffic spikes.
  • Operations Monitoring – API Gateway provides a metrics dashboard to monitor calls to services.
  • Lifecycle Management – Operate multiple API versions and multiple stages for each version simultaneously so that existing applications can continue to call previous versions after new API versions are published.

API Gateway provides robust, secure, and scalable access to backend APIs and hosts multiple versions and release stages for your APIs.

You can create and distribute API Keys to developers.

Option to use AWS Sig-v4 to authorize access to APIs.

You can throttle and monitor requests to protect your backend.

API Gateway allows you to maintain a cache to store API responses.

SDK Generation for iOS, Android, and JavaScript.

Reduced latency and distributed denial of service protection using CloudFront.

Request/response data transformation and API mocking.

Resiliency through throttling rules based on the number of requests per second for each HTTP method (GET, PUT).

Throttling can be configured at multiple levels including Global and Service Call.

A cache can be created and specified in gigabytes (not enabled by default).

Caches are provisioned for a specific stage of your APIs.

Caching features include customizable keys and time-to-live (TTL) in seconds for your API data which enhances response times and reduces load on back-end services.

API Gateway can scale to any level of traffic received by an API.

Logging and Monitoring

The Amazon API Gateway logs (near real time) back-end performance metrics such as API calls, latency, and error rates to CloudWatch.

You can monitor through the API Gateway dashboard (REST API) allowing you to visually monitor calls to the services.

API Gateway also meters utilization by third-party developers and the data is available in the API Gateway console and through APIs.

Amazon API Gateway is integrated with AWS CloudTrail to give a full auditable history of the changes to your REST APIs.

All API calls made to the Amazon API Gateway APIs to create, modify, delete, or deploy REST APIs are logged to CloudTrail.

Understanding the following metrics is useful for the exam:

  • Monitor the IntegrationLatency metrics to measure the responsiveness of the backend.
  • Monitor the Latency metrics to measure the overall responsiveness of your API calls.
  • Monitor the CacheHitCount and CacheMissCount metrics to optimize cache capacities to achieve a desired performance.

Open API / Swagger

Can import existing Swagger / Open API 3.0 definitions (written in YAML or JSON) to API Gateway.

This is a common way of defining REST APIs using API definition as code.

Can also export current APIs as Swagger / Open API 3.0 definition.

Uses the API Gateway  Import API feature to import an API from an external definition.

With the import API you can either create a new API by submitting a POST request that includes a Swagger definition in the payload and endpoint configuration or you can update an existing API by using a PUT request that contains a Swagger definition or merge a definition with an existing API.

You specify the options using a mode query parameter in the request URL.


With Amazon API Gateway, you only pay when your APIs are in use.

There are no minimum fees or upfront commitments.

You pay only for the API calls you receive, and the amount of data transferred out.

There are no data transfer out charges for Private APIs (however, AWS PrivateLink charges apply when using Private APIs in Amazon API Gateway).

Amazon API Gateway also provides optional data caching charged at an hourly rate that varies based on the cache size you select.

The API Gateway free tier includes one million API calls per month for up to 12 months.

Related posts: