AWS API Gateways Critical Review

Stages: A mistake AWS cannot take back

I’ve tried not to turn this story into a rant… I’m not sure I succeeded. However, I’ve have sent this story to AWS in hope they take some of the feedback on board.

AWS API gateways and I have a very much a love hate relationship. I love the idea, can see what AWS are trying to do, but they have some serious design flaws that need to be addressed.

The idea behind API gateways is that you can define your HTTP based API (REST/Websockets), define a model to be validated, define how the API integrates with an aws resource (such as a Lambda) and how the integration response is mapped to the API response.

All sounds good so far, but let’s have a look at those design flaws…

Stages

By far the biggest flaw in my mind is API Gateway Stages.

AWS defines a stage as…

A stage is a named reference to a deployment, which is a snapshot of the API. You use a Stage to manage and optimize a particular deployment. For example, you can set up stage settings to enable caching, customize request throttling, configure logging, define stage variables or attach a canary release for testing. See here

So the idea is that the Stage can be considered a specific lifecycle state or version of your API. E.g. maybe you have a dev-stage or v1 of your API and against these different stages you can have things like throttling and caching.

Stages throw up an interesting and annoying problem.

Unlike most AWS resources, where cloudformation is used to defined the desired state and then take you to that desired state on deployment, the API Gateway concept of Stages massively muddles this and forces Cloudformation to do some form of API orchestration.

When using SAM, as I understand it there is a algorithm within SAM which determines whether the Deployment resource should be recreated. This algorithm does not cover all possible changes to API GWs (such as adding a new path). Thus you can a new path, deploy your template successfully, but because of the API has not be deployed to the Stage (Grrrr stages) it is never updated. We’ve found the only way around this is to Deploy manually using the console or delete the stack.

My opinion on this is that although Stages may provide some flexibility in configuration, they potentially introduce some anti-patterns into some unsuspecting developers API. For example, there are many strategies for configuring different environments in AWS. One of the least scalable would be to have all environments under a single account.

How about versioning? Well, there is quite an emotional debate around the best way of doing this or if you should. I quite enjoyed this article on the subject.

With these things in mind why are Stages not optional in AWS? You have to use a Stage if you want to deploy an API. Which could lead you down a route that you were not expecting.

Incidentally, the way I handle Stages is to create a single Stage and constantly update it. Call it ‘/Prod’ or something meaningful for you and try and move on.

The problem now of course is that due to backward compatibility Stages will be with us forever.

Gateway API UI

One of the annoying issues with AWS is that each Resource console is very different and offers varying levels of functionality and UI experience. It certain feels like Conways law in action.

But there is so much wrong with the Gateway API console is hard to know where to begin. It’s death by a thousand cuts — poorly designed and hard to use.

Linking

Let’s start with the linking from Cloudformation to the Gateway API.

Wouldn’t it be nice if the link from cloudformation to the API Gateway console actually took you to the API you just clicked on? Yes, yes it would. Does it? Does it hell. It takes you to the root of your APIs. A small but annoying problem. But exacerbated by…

Navigation

The console extremely non scalable from a UI perspective. If you have more than around 20 gateways in your account on the same region is becomes very hard to find what you are looking for. If you have multiple different systems using a microservices architecture then this can get very unusable very quickly. If you have long API names then this problem is increased.

Having lots of API gateways also causes other annoyances — If you open an API gateway on the left hand side navigation and click on Stages you’ll have to scroll all the way to the top to actually see what you’ve clicked on.

The left hand navigation is also non-movable. Very frustrating when you can’t see the full name of the gateway.

Custom Domain Names

Custom domain names reserve a special place in my heart for being extremely awkward (I’ll save this for another story). In terms of UX finding custom domain names is easier enough, however, finding the API gateway they are linked to is a manual process once again. Why is there not a link to the gateway that is mapped? Small by annoying problems.

In conclusion, the UX for API gateways feels like it’s been put together very hastily and in no way scales. In comparison to some of the other AWS Resource Consoles API API gateways needs some serious work.

Documentation

One of my big pieces of feedback to AWS would be to work on there documentation. Each Resource should be backup with examples of how to configure and create using both Cloudformation and SAM.

In conclusion

We will continue to use API Gateway for REST based APIs in our system. Hopefully AWS will change some of these small but very frustrating customer journeys focusing around documentation and UX on the console. In the longer term, I’d love to see Stages disappear and cleaner and simpler integration with Cloudformation.