API Gateway

Amazon API Gateway is an API management service that allows you to create, publish, monitor, and maintain APIs at scale. You can use it to front microservices on Lambda, EC2, or S3 without writing integrations. It offers an easier to manage approach to scaling as ELB configuration is managed by AWS.


  • APIs are the root of the configuration and define resources. These can be imported from OpenAPI/Swagger definitions.
    • Resources define URLs.
    • Resource Policies allow per-method control over which callers are permitted to perform which operations.
    • IAM Policies can be used if the method's "Authorisation" is set to AWS_IAM.
    • Methods define actions that are taken for specific HTTP methods.
    • Integration types allow handing off requests to a backend for processing.
    • Stages represent environments (e.g. development, pre-production, production or an API version).
    • Authorisers are Lambda functions which can authenticate and authorise users against external sources of user data. Responses from the Lambda function can be cached to reduce costs and improve performance. Based on the Lambda response, the API Gateway will either execute the method or return a 403.
    • Gateway Responses allow configuration of errors pages preventing the API Gateway from submitting the request to the integration.
    • Models define the data structures for request payloads.
    • Documentation is comprised of document parts.
  • Usage Plans allow limiting API consumption per API key. Lower limits can be set per-method.
  • API Keys are used for authentication, authorisation and throttling. They enable differentiating between clients.

Method execution

API requests and responses can be transformed by the API Gateway service, via mapping templates written in Apache VTL.

Integration types

Integrations allow the API Gateway to hand off requests onto other AWS or external services for processing:

  • Lambda Function lets you hand off processing to a Lambda function.
  • HTTP allows proxying the request to another API.
  • Mock causes the API Gateway to generate valid responses
  • AWS Service provides integrations for e.g. DynamoDB or S3.


Stages allow modelling API versions or deployment environments.

Client SDK generation for a stage's currently deployed version is supported for several languages.

Request throttling

Request throttling, by rate and burst (maximum concurrent requests) and response caching can be enabled for all methods within:

  • An AWS account
  • A stage
  • A usage plan


  • Per-method
  • Per-client

Throttled requests will receive a 429.


Quotas can be assigned per-day, per-week and per-month for each API key.


API Gateway instances can be configured to send and process CORS headers on behalf of the application, reducing application complexity.


Changes to API configuration are versioned, with a new Deployment being created for each version once it's deployed to a stage. These deployments can be promoted to other stages using their creation time as an identifier. Changes only take effect once the Deployment is applied to a Stage.

Canary release

Canary deployment can be enabled per-stage, allowing you to split traffic between the new and old deployments at set percentages until you're ready to fully promote a version.