Introduction
Amazon API Gateway is a fully managed service through which application programming interfaces are created, published, secured, and monitored. An application programming interface, known as an API, is a defined set of endpoints through which one program requests data or actions from another. This guide explains what API Gateway is, the problem it was created to solve, how it processes a request, and the situations in which it is appropriate.
What is it?
API Gateway acts as the front door for an application. Requests from clients are received by the service, which then routes each request to the correct backend, applies security and rate controls, and returns the response. A client is any program that makes a request, for example a web browser or a mobile application. A backend is the service that performs the work, for example an AWS Lambda function or an HTTP server.
Two principal API types are offered. A REST API provides the fuller feature set, and an HTTP API provides a smaller feature set at lower cost and latency. A third type supports WebSocket connections for two-way, real-time communication.
Why does it exist?
An API that is exposed to the public must perform several tasks that are unrelated to its core logic. Requests must be routed to the correct handler, callers must be authenticated, the rate of requests must be limited so that the backend is not overwhelmed, and traffic must be monitored. If these tasks were implemented separately for every service, a large amount of duplicated effort would be required. API Gateway was created so that these concerns are handled by a single managed service, which allows the backend to focus on business logic.
How it works
An API in API Gateway is composed of resources and methods. A resource is a path, for example /orders. A method is an HTTP verb on that path, for example GET or POST. Each method is connected to an integration, which defines the backend that is called and how the request and response are mapped.
When a request arrives, the path and method are matched to a configured resource. An authorizer may then be invoked to verify the caller. An authorizer is a component that confirms identity and permissions, and it may be based on Amazon Cognito or on a custom Lambda function. Throttling, which is the deliberate limiting of the request rate, is applied so that the backend is protected. The request is then passed to the integration, and the response is returned to the client. Each deployed version of an API is published to a stage, for example a stage named prod, so that separate versions can be maintained.
Architecture diagram
Advantages
- Fully managed. Routing, scaling, and availability are handled by AWS.
- Built-in security. Authentication, authorization, and throttling are provided without custom code.
- Direct integration. Lambda functions and several AWS services can be called without an intermediate server.
- Monitoring. Request metrics and logs are produced automatically.
- Versioning. Stages allow multiple versions of an API to be run side by side.
Disadvantages
- Cost at scale. The per-request charge can become significant at very high volume.
- Added latency. A small amount of processing time is added to each request.
- Configuration complexity. Larger APIs with many resources and mappings can be intricate to manage.
- Service limits. Payload sizes and timeouts are bounded and must be considered.
Common use cases
- Serverless web and mobile backends, in which requests are routed to Lambda functions.
- A single, unified entry point placed in front of several backend services.
- Webhooks, in which events from external systems are received over HTTP.
- Public APIs for which usage plans and rate limits are required.
Best practices
- An HTTP API should be preferred when its features are sufficient, because it is less expensive and faster.
- Authentication should be enforced with an authorizer rather than being implemented inside each backend.
- Throttling limits should be set so that a sudden surge does not overwhelm the backend.
- Stages should be used to separate development, testing, and production.
- Access logs and metrics should be reviewed through Amazon CloudWatch.
Common mistakes
- A REST API is chosen when an HTTP API would be sufficient, which increases cost and latency.
- Throttling is not configured, which leaves the backend exposed to overload.
- CORS is not configured, so browser-based clients are unable to call the API.
- Authentication is omitted, so endpoints are left open to the public.
Related AWS services
- AWS Lambda is the most common backend for an API and runs the logic behind each endpoint.
- Amazon Cognito provides authentication that an authorizer can use to verify callers.
- AWS WAF, the Web Application Firewall, filters malicious requests before they reach the API.
- Amazon CloudWatch collects the access logs and metrics that the API produces.
Frequently Asked Questions
- What is the difference between a REST API and an HTTP API in API Gateway?
- A REST API provides the fuller feature set, including request validation, response caching, and usage plans. An HTTP API provides a smaller feature set at lower cost and latency. The HTTP API should be chosen when its features are sufficient.
- How is Amazon API Gateway priced?
- Charges are based on the number of API calls that are received and, for REST APIs, on any response caching that is enabled. HTTP APIs are generally less expensive per request.
- Can API Gateway call backends other than AWS Lambda?
- Yes. In addition to invoking Lambda functions, API Gateway can forward requests to any reachable HTTP endpoint and can integrate directly with several AWS services.
- What is an authorizer?
- An authorizer is a component that verifies the identity and permissions of a caller before a request reaches the backend. Authorizers can be based on Amazon Cognito or on a custom Lambda function.
- Does API Gateway handle CORS?
- Yes. Cross-Origin Resource Sharing, known as CORS, is a browser mechanism that controls whether a web page may call an API on a different domain. API Gateway can be configured to return the headers that CORS requires.
This article is the summary. The book is the full, continuously updated reference: production API designs, authentication, throttling, and complete serverless architectures.
View the book