AWS API Gateway in Production: Failure Clinic (Course #aws-apigw-clinic)
For platform engineers, SREs, API developers, cloud architects.
By the end, you can
By the end of this course, you will be able to operate an Amazon API Gateway estate against its published limits — a ceiling register, an account-level throttle budget and a request-transformation test suite — so that a neighbouring team's traffic and a dropped header both stop being discovered in production.
Running case study
Pellingham Grocers runs storefront, fulfilment and supplier APIs as a mix of REST and HTTP APIs in one AWS account and Region, peaking at 4,100 req/s during Thursday promotions. A supplier batch endpoint was throttled during a promotion by traffic from an unrelated team, and a separate incident took 3 days to diagnose because the request bodies needed to reproduce it were never in the logs. Engineering wants every platform ceiling registered and every gateway-imposed transformation covered by a test before the next peak season.
Programme every line is something you do
4 modules · 12 topics · in course-flow order
-
Module 1
One account, one throttle budget
Objective. Model the account-level throttle quota as a shared resource and allocate it deliberately across teams.
- Establish the shared ceiling: the throttle quota is per account per Region across HTTP, REST, WebSocket and WebSocket callback APIs
- Check the Region before assuming headroom — 13 named Regions default to 2,500 RPS and 1,250 burst rather than 10,000
- Allocate per-stage and per-method throttles so no single API can consume the shared budget, and note the burst bucket is not customer-controllable
-
Module 2
Ceilings you meet by accident
Objective. Register the configuration ceilings a design crosses and price the trade-off each raise carries.
- Trade timeout against throughput: raising the integration timeout from 29 s toward 300 s may require reducing the account-level throttle quota
- Check eligibility before designing around it, since edge-optimized REST APIs and HTTP APIs cannot take the increase
- Register the silent ceilings — 300 KB mapping templates, 128 KB WebSocket payloads with 32 KB frames closing on code 1009, and a non-customisable 413 response
-
Module 3
The request the backend receives
Objective. Diff client request against backend request and cover every gateway-imposed transformation with a test.
- Locate the identity break: the Authorization header is dropped when it carries a SigV4 signature or AWS_IAM authorization is used, and others are remapped to X-Amzn-Remapped-*
- Test content negotiation, since only the first Accept media type is honoured and binary handling depends on the binaryMediaTypes list
- Cover the 3 query-string hazards — a semicolon splits the data, pipes and braces must be URL-encoded, and parameters are case-sensitive
-
Module 4
Evidence and contract fidelity
Objective. Close the two gaps that make incidents unreproducible: missing payload evidence and silent contract loss at import.
- Work around truncation at 1024 bytes per log event, which removes request and response bodies from the gateway's own audit trail
- Site the payload evidence you need elsewhere, with a sampling rate and retention target agreed before the next peak season
- Diff the imported API against the source specification, since default, nullable, example, discriminator and readOnly are unsupported and root-level security is ignored
References & Official Documentation every claim above has a source
Module 1
- Amazon API Gateway quotasMuleSoft Docs
- Throttle requests to your REST APIsMuleSoft Docs
Module 2
- Amazon API Gateway important notesMuleSoft Docs
- API Gateway integration timeout limit increase beyond 29 secondsMuleSoft Docs
- WebSocket APIs in API GatewayMuleSoft Docs
Module 4
- OpenAPI Specification 3.1.0Specification
- Configure a REST API using OpenAPIMuleSoft Docs
- Set up CloudWatch logging for a REST APIMuleSoft Docs