I’ve been working with serverless tech like AWS Lambda and AWS API Gateway for quite a while now, but only recently was the first time I built an API using those technologies that was meant for public consumption, rather than just internally by my own front-ends.
I love the process of putting myself in the shoes of an external developer and thinking about how to make the API as easy to use as possible, with clear route names and error codes.
Here are some of the main things to consider when building your API using AWS serverless tools:
REST or HTTP API?
API Gateway lets you choose between two different types of APIs: REST or HTTP.
These have quite a few differences. The full comparison can be found in the AWS documentation. Here’s a quick summary:
- REST APIs: the older generation. This has a lot more options for customisation, like custom response mapping for built-in gateway errors, built in API key management, caching, and advanced throttling. In the Serverless framework, this is available under the name
- HTTP APIs: newer generation. Much simpler in terms of built-in features, but cheaper. This is the default option for most of the APIs I build, but depending on your requirements you might decide to go for REST APIs instead. Serverless framework name:
Consistent error messages
For a public-facing API, having consistent error messages is important. It might also mean you need to respond with errors in a slightly more structured way than you do for internal APIs.
Where for an internal API something like this might be sufficient:
"error": "Invalid document visibility setting."
For an external-facing API, you might want to also return an error code, which will allow your clients to map these to their own error messages, and return any relevant links to help developers. The JSON API specification has a nice structure for this, which roughly looks like this:
"title": "Invalid document visibility setting.",