As convenient and powerful as AWS API Gateway is, it’s not without its quirks. Here are a few lessons I’ve learned the hard way that can help you avoid some common pitfalls when working with AWS API Gateway.
1. Need a Custom CloudFront Distribution for Lambda@Edge
If you’re using Lambda@Edge, you may find that API Gateway doesn’t provide the flexibility you need out of the box. You’ll need to set up a custom CloudFront distribution to ensure things like caching and routing work as expected. (In particular, the distribution that a custom domain manages under the covers and edge-optimized endpoints won’t do.) A CloudFront distribution enables Lambda@Edge to run in multiple AWS regions, ensuring low latency and high availability, but getting this right can involve extra setup and complexity. Be prepared to configure your distribution to suit your Lambda@Edge needs.
2. Stage Variables Take Effect Without a Deploy
It might come as a surprise, but changes to stage variables in API Gateway are reflected immediately without requiring a formal deployment. Unlike other API updates that need to be pushed via a deploy, changing stage variables immediately impacts the behavior of your API, even in production. While this can be convenient, it’s also risky if you’re not cautious. Always double-check your stage variables to avoid accidentally introducing changes in a live environment.
3. CloudFront Distributions and Custom Domains Interact
This is a big one. Custom CloudFront distributions and API Gateway custom domains can clash in surprising, undocumented ways. If you decide to go with a custom CloudFront distribution for your API, you need to remove any existing custom domains in API Gateway first. Failing to do so can result in a tangled configuration that’s hard to untangle and reason about. The official AWS documentation provides a step-by-step guide on how to set up custom CloudFront distributions with API Gateway—follow it carefully. Otherwise, you may end up with requests not routing as expected or even failing completely.
In my case, I had a custom hostname and a custom CloudFront distribution active at the same time. Both were configured to use the hostname api.example.com, but DNS records were pointing to the CloudFront distribution. When I tried to duplicate my production environment, it took several hours to figure out that my custom CloudFront distribution was routing to my production API Gateway stage because of the API custom hostname and not because of the stage name prefix, as expected. Confirming the theory and untangling the mess resulted in an hour of downtime. Don’t make my mistake!
4. Manage Your API in API Gateway, Then Export the Spec
One important practice to follow is: manage your API directly in API Gateway, then export the OpenAPI spec for use elsewhere. You can import an OpenAPI spec to initialize your API Gateway, but after that, trying to import an OpenAPI spec back into API Gateway, especially if it was modified outside the console, can lead to unexpected errors and lost configurations. By keeping API Gateway as the source of truth and exporting the spec when needed, you can avoid issues with missing configuration details or unsupported features.
5. API Gateway Does Not Support Discriminators
If your API design involves polymorphism or you’re relying on discriminators in your OpenAPI spec, note that API Gateway does not support this feature. Discriminators allow you to specify which schema to use based on a field in the JSON body. Unfortunately, API Gateway’s OpenAPI integration won’t handle this natively. You’ll need to work around this by implementing custom logic in your backend or through request validation in Lambda functions. I recommend integrating an OpenAPI spec linting tool like spectral with custom API Gateway rules into your OpenAPI design process or CI/CD to avoid unhappy surprises.
6. Authenticators Are Part of the Spec: Handle with Care
When working with custom authentication schemes or OAuth2 flows in API Gateway, be aware that lambda authorizers are stored in API Gateway as part of your OpenAPI spec. If you’re not careful during spec modifications or exports/imports, you may inadvertently wipe out authentication settings. Always check your authenticator settings after making changes to the spec, especially if you’re importing changes from an external tool.
7. API Gateway Does Not Generate 406 Errors
API Gateway doesn’t support 406 Not Acceptable errors out of the box. While API Gateway performs basic content negotiation by inspecting the Accept header, it doesn’t generate a 406 response if the requested format isn’t supported. This means the API won’t explicitly inform the client when it cannot fulfill the requested content type—it just returns a default response. You’ll need to implement custom error handling if strict content negotiation is important for your use case.
Conclusion
AWS API Gateway is incredibly useful for building and managing APIs, but like any tool, it has its “gotchas.” By being aware of the quirks mentioned above and planning for them, you can avoid some of the common pitfalls and keep your API development process running smoothly.
If you’ve encountered any other surprises with API Gateway, let me know in the comments below!