AWS API Gateway gotchas

I enjoy this era of accessible and affordable cloud services as much as the next developer. But where gotchas exist, they should be noted, for my own reference at least. This is a running list of things I've encountered working with AWS' API Gateway.

When methods on a resource don't exist, the response is 403

In other words if you're making a POST to an endpoint that only has PUT, API Gateway will tell you you don't have credentials and might even give you a CORS error in your console. This will send you down the wrong rabbit hole thinking you misconfigured something in your method or integration response.

Specifically, a request with a method that doesn't exist on a resource returns a 403 Forbidden error when it should instead return a 405 Method Not Allowed error. A post on the AWS forms from 2015 addresses the issue and someone from AWS responded saying they would add it to the backlog in 2016, but I'm still getting this issue in 2019. The W3 spec definition for a 405 error matches this case exactly:

10.4.6 405 Method Not Allowed:
The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response MUST include an Allow header containing a list of valid methods for the requested resource.

Header names are processed as case sensitive

In AWS' list of known issues, they say:

API Gateway enacts the following restrictions and limitations when handling methods with either Lambda integration or HTTP integration: Header names and query parameters are processed in a case-sensitive way.

But according to the W3 spec, header names should be case insensitive:

Each header field consists of a name followed by a colon (":") and the field value. Field names are case-insensitive.

In the scenario I encountered this issue, this quirk was compounded by the fact that the fetch polyfill by GitHub that so many projects use (including ours) lowercases header names. This is the polyfill recommended in Google's web developer documentation and by MDN, the two most authoritative sources of technical documentation for the web aside from the official W3 spec. So if your backend services or your configured request headers in API gateway use the standard capitalization for header names (e.g. Content-Type), you're in for a world of hurt.

Thanks for reading! Go home for more notes.