AWS 144: Amazon API Gateway
Why this lesson matters
Choose HTTP, REST, or WebSocket APIs by protocol and feature needs, then design routes, integrations, authorization, throttling, deployment, and observability.
What you will be able to do
By the end, you can:
- explain amazon api gateway in plain language;
- locate the current service controls in the AWS Management Console;
- run the matching CloudShell or AWS CLI queries and explain every important field;
- draw the identity, network, data, failure, and monitoring path;
- choose the service from requirements and reject it when those requirements are absent;
- diagnose a failed or misleading result from evidence;
- state the cost owner and prove cleanup or a no-create result.
Before you start
- Use a personal AWS account only when its owner has approved the lesson. Do not use the root user for daily work.
- CloudShell is the default command environment. AWS028 explains CloudShell; AWS029 and AWS030 explain local AWS CLI installation and profiles.
- The course example Region is
ap-south-1. Global services and services with a required control Region are called out in their commands. - Run
aws sts get-caller-identityprivately. Redact the account number before sharing evidence. - Never paste access keys, passwords, secret values, private object data, presigned URLs, or full account-specific ARNs into a submission.
- This is a no-create lesson. Every Console action and AWS CLI command is read-only. Create the practical artifact locally.
- Console wording can change. Use the Console service search if a menu label has moved, then confirm the current field in the official documentation.
The core model
| Question | What it means in this lesson |
|---|---|
| Purpose | Choose HTTP, REST, or WebSocket APIs by protocol and feature needs, then design routes, integrations, authorization, throttling, deployment, and observability. |
| Scope and boundary | The learner must identify the account and Region scope, resource boundary, identity path, data or network path, failure behavior, observability, and cleanup ownership for Amazon API Gateway. |
| Evidence of success | Success means the Console fields, CLI result, workload behavior, monitoring evidence, and architecture claim agree. An available state alone is not enough for Amazon API Gateway. |
| Cost model | Requests, running capacity, storage, logs, data transfer, retained state, and optional features must be priced for the exact design. |
| Safe rejection rule | Avoid making every backend error a 200 response or exposing an unprotected public route because the integration is private. |
How the request flows
+-----------------------------+
| HTTPS or WebSocket client |
+-----------------------------+
|
v
+--------------------------------+
| Route, authorizer, and stage |
+--------------------------------+
|
v
+----------------------+
| Integration |
+----------------------+
|
v
+------------------------------------+
| Response, access log, and metric |
+------------------------------------+For Amazon API Gateway, the important boundary is this: The learner must identify the account and Region scope, resource boundary, identity path, data or network path, failure behavior, observability, and cleanup ownership for Amazon API Gateway. Success means the Console fields, CLI result, workload behavior, monitoring evidence, and architecture claim agree. An available state alone is not enough for Amazon API Gateway. That is why the lesson pairs the Console with CLI output and a practical artifact. One interface may hide a field, use a cached view, or be scoped differently. Matching evidence is stronger than a screenshot alone.
Architecture decision table
| Situation | Direction | Reason |
|---|---|---|
| Requirement matches | Use API Gateway when managed API routing, authorization, throttling, transformations, stages, or WebSocket handling fit. | Select only after scope, behavior, security, recovery, operations, and price evidence agree. |
| Requirement does not match | Avoid making every backend error a 200 response or exposing an unprotected public route because the integration is private. | Rejecting an attractive service is a valid architecture result. |
| No create permission or cost approval | Use supplied evidence and local design work | Learning does not depend on creating an hourly resource. |
| Existing resource is unknown or unowned | Inspect only, then stop | Never change or delete a resource merely because it resembles a course example. |
Choose the API product before building routes
| Product | Starting fit | Qualify carefully |
|---|---|---|
| HTTP API (v2) | lower-cost HTTP routing, Lambda/HTTP integrations, JWT/Lambda/IAM authorization | feature parity with REST is incomplete; verify validation, transformation, caching and private-endpoint needs |
| REST API (v1) | mature REST features including API keys/usage plans, validation/transformation, caching and private REST APIs | higher complexity/cost; API keys are not primary authentication |
| WebSocket API | persistent two-way connections and connection routes | connection state, callback authorization, stale connections and per-message/connection cost |
Frontend exposure and backend exposure are separate. A private integration uses a VPC link to reach supported private backends; it does not make a public API route private. Protect clients with supported IAM SigV4, Cognito/JWT, Lambda authorizer or resource policy, and WAF where applicable. Validate issuer, audience, scopes and route authorization. CORS is a browser rule, not authentication.
The path is DNS/TLS/custom domain -> endpoint policy/WAF -> route -> authorizer -> validation/mapping -> integration -> response mapping -> access log. Lambda permission to be invoked is distinct from its execution role. Service integrations can call AWS APIs through a scoped integration role without Lambda. Stages/deployments determine what is live; auto-deploy needs change control. Custom domains combine an ACM certificate in the required Region, API mapping and DNS alias.
Throttling is token-bucket protection, not guaranteed isolation. Set account/stage/route/usage controls as supported, return meaningful 429, and protect backend connections/concurrency. Use structured access logs with request ID, route, principal, status, integration status/latency and response size; redact sensitive data. Distinguish API latency, integration latency and client-observed latency.
AWS Management Console, step by step
Sign in with the normal non-root learning identity. Write the expected starting state before opening the service.
- Use the Console service search and open API Gateway, APIs; confirm the account and Region before reading the page.
- Inspect the supplied or owned resource's status, configuration, permissions, networking, encryption, monitoring, tags, and dependencies without changing it.
- Open the related metrics, logs, events, or history view and record one timestamped signal that would prove or disprove the expected behavior.
- Return to the resource list, clear filters, and record the final inventory. On the read-only track, do not choose Create, Save, or Delete.
CloudShell and AWS CLI, step by step
Start with a known caller and Region:
export AWS_DEFAULT_REGION="ap-south-1"
aws sts get-caller-identity --query Arn --output text
aws configure listRedact the account part of the ARN in shared evidence. Now run the topic queries:
aws apigatewayv2 get-apis --query 'Items[].{Name:Name,Protocol:ProtocolType,Endpoint:ApiEndpoint}' --output table
aws apigateway get-rest-apis --query 'items[].{Name:name,Id:id,Created:createdDate}' --output tableExpected interpretation
The two APIs distinguish v2 HTTP or WebSocket resources from REST APIs. Neither inventory proves route authorization, backend health, mapping correctness, or client latency.
Practical work
Create an API contract for POST /orders and GET /orders/{id}. Choose API type, authorizer, validation, integration timeout, throttling, access logs, error mapping, CORS, stage, and custom-domain path.
Add examples for 2xx, validation 400, unauthenticated 401, unauthorized 403, missing 404, conflict 409, throttled 429 and dependency 5xx. Define POST idempotency. Test wrong-audience JWT, invalid body, wrong stage, absent Lambda permission, backend timeout, burst throttle, malformed proxy response, CORS preflight and DNS/certificate rollback. Compare API Gateway with ALB, Function URL and direct service access.
Diagnose this topic from its own evidence
No access log suggests DNS/TLS/WAF/resource policy or wrong endpoint. Gateway 401/403 points to auth/policy; 404 often means route/stage/mapping; 429 requires throttle evidence; 502 commonly means malformed integration output or backend failure; 504 is integration timeout. Correlate API request ID, access/authorizer logs, integration request ID and backend trace. Never map all failures to HTTP 200 or disable authorization as a fix.
Cost and cleanup
Requests, running capacity, storage, logs, data transfer, retained state, and optional features must be priced for the exact design.
Knowledge check
- What operational purpose is this lesson solving?
Expected direction: Choose HTTP, REST, or WebSocket APIs by protocol and feature needs, then design routes, integrations, authorization, throttling, deployment, and observability.
- Which scope or ownership boundary must be proved first?
Expected direction: The learner must identify the account and Region scope, resource boundary, identity path, data or network path, failure behavior, observability, and cleanup ownership for Amazon API Gateway.
- What evidence is strong enough to accept the result?
Expected direction: Success means the Console fields, CLI result, workload behavior, monitoring evidence, and architecture claim agree. An available state alone is not enough for Amazon API Gateway.
- Which tempting design or shortcut must be rejected?
Expected direction: Avoid making every backend error a 200 response or exposing an unprotected public route because the integration is private.
- Which cost dimensions and retained resources need an owner?
Expected direction: Requests, running capacity, storage, logs, data transfer, retained state, and optional features must be priced for the exact design.
Lesson acceptance
Pass when the learner chooses HTTP, REST or WebSocket API from feature evidence; traces every request layer; specifies auth, validation, status contracts, idempotency, throttling, stages, private integration, custom-domain TLS and observability; and passes negative/rollback tests. Fail if API keys/CORS are called authentication, a private backend is assumed to make the API private, or failures are masked as success.