Amazon API Gateway: A Comprehensive Cheat Sheet

What is Amazon API Gateway?

Amazon API Gateway is a fully managed AWS service that enables developers to create, publish, maintain, monitor, and secure APIs at any scale. It acts as a "front door" for applications to access data, business logic, or functionality from your backend services, such as workloads running on Amazon EC2, code running on AWS Lambda, or any web application. API Gateway handles all the tasks involved in accepting and processing up to hundreds of thousands of concurrent API calls, including traffic management, CORS support, authorization and access control, throttling, monitoring, and API version management.

Core Concepts

• API Deployment: A point-in-time snapshot of your API's resources and methods. To be used by clients, a deployment must be associated with one or more stages.

• API Stage: A logical reference to a lifecycle state of your API (e.g., dev, prod, beta). It's a snapshot of the API and is made available for client applications to call. Stages are identified by the API ID and stage name.

• API Key: An alphanumeric string that you can distribute to application developer customers to grant access to your API. You can use API keys together with usage plans or Lambda authorizers to control access.

• Usage Plan: Defines who can access one or more deployed API stages and methods, and also sets the target request rate (throttling) and quota limits.

• Model: A data schema that defines the data structure of a request or response payload. Models are defined using the JSON Schema draft 4.

• Integration: The connection between an API Gateway method and a backend endpoint.

  • Proxy Integration: A simplified integration configuration. API Gateway passes the entire request and response between the frontend and the backend. Available as Lambda Proxy and HTTP Proxy.

  • Private Integration: Allows a client to access resources inside a customer's VPC through a private API endpoint without exposing the resources to the public internet.

API Types: REST vs. HTTP vs. WebSocket

API Gateway supports three distinct types of APIs, each serving different needs.

HTTP APIs

The newer generation of APIs, designed for low-latency, cost-effective integrations.

• Best for: Building proxy APIs for serverless Lambda functions or HTTP backends, and for workloads that don't require the extensive feature set of REST APIs.

• Features: Supports OIDC and OAuth 2.0 authorization, custom domains, VPC link integrations, and provides a simpler, faster, and cheaper solution compared to REST APIs.

REST APIs

The classic, more feature-rich API offering.

• Best for: Complex API requirements that need features like API keys, per-client throttling, request validation, AWS WAF integration, or private API endpoints.

• • Features: Provides a wider range of security and management features, making it suitable for enterprise-grade public-facing APIs.

WebSocket APIs

Build stateful, real-time, two-way communication applications.

• Best for: Real-time applications like chat apps, live dashboards, and streaming updates where the server needs to push messages to connected clients.

• Features: Maintains a persistent connection between the client and server, allowing both to send messages to each other at any time.

API Endpoint Types

• Edge-Optimized: The default endpoint type. Requests are routed through the nearest CloudFront Point of Presence (PoP), which is ideal for geographically distributed clients.

• Regional: The API is deployed within a specific AWS Region. Requests are targeted directly to the region-specific API Gateway, which can reduce latency for clients in the same region.

• Private: Exposes your API through interface VPC endpoints, allowing secure access only from within your Amazon VPC or from networks connected to your VPC.

Key Features

• Custom Domains: You can use your own domain names (e.g., api.example.com) for your APIs.

• Data Mapping: Transform request and response data between your API and the backend integration.

• Documentation: Create and manage documentation for each part of your API.

• HTTPS Only: All APIs created with API Gateway expose HTTPS endpoints only, ensuring communication is always encrypted.

• Wildcard Custom Domains: Use wildcard custom domain names (e.g., *.example.com) to route requests for multiple URLs to a single API Gateway HTTP API.

Security

• Authentication & Authorization:

  • IAM Permissions: Use AWS IAM roles and policies to authorize access to your APIs.

  • Lambda Authorizers (formerly Custom Authorizers): Use a Lambda function to perform bearer token authentication (e.g., OAuth, SAML) or other custom authorization logic.

  • Amazon Cognito User Pools: Integrate with Cognito to handle user authentication, authorization, and management for your web and mobile apps.

  • API Keys: Use API keys to track and control app access to your APIs.

• Traffic Protection:

  • AWS WAF: Protect your APIs from common web exploits like SQL injection and cross-site scripting (XSS).

  • Throttling & Quotas: Configure usage plans to set throttling and quota limits on a per-client basis.

Performance & Scaling

• Caching: You can enable API caching to cache your endpoint's responses. Caching reduces the number of calls made to your backend and improves latency for requests to your API.

• Burst & Rate Limiting: API Gateway throttles requests to your API to prevent it from being overwhelmed by too many requests. Default limits can be increased upon request. It integrates seamlessly with AWS Lambda to handle sudden bursts in traffic.

Monitoring & Logging

• Amazon CloudWatch Integration:

  • Metrics: API Gateway is automatically integrated with CloudWatch, providing detailed metrics like API calls, latency, and error rates in one-minute periods. You can create custom alarms on these metrics.

  • Logs: You can enable CloudWatch Logs to record API execution errors or full request/response logs for debugging and analysis.

Pricing Model

API Gateway has a pay-as-you-go pricing model with no minimum fees or upfront commitments.

• API Calls: You pay for the number of API calls you receive.

• Data Transfer: You pay for the data transferred out from the API Gateway to the internet.

• Caching: If you use optional data caching, you are charged an hourly rate based on the cache size you select.

Note: HTTP APIs are offered at a significantly lower price point compared to REST APIs.