Preventing Your API From Sucking

There are so many factors that go into success — market, product, requirements, customers, oh, the list goes on. That said, there are a couple of things that you must do to make sure that failure isn’t guaranteed. The following list isn’t exhaustive, but it is, most definitely, table-stakes these days for how you should structure your APIs.

1. 1. Respect Every API: You don’t really know which API is going to be used, and which one isn’t. Murphy’s law pretty much guarantees that the throwaway buggy one that you put out there is going to be the one that causes you the most trouble. And Hyrum’s law will ensure that that shitty implementation will be made concrete, and you’ll never get rid of it.
2. 2. Be Obvious: Make sure that there are no surprises. No unexpected side-effects, no behavior that isn’t documented. Seems like such a small thing, but, in the end, it’s the side-effects and/or hidden features that will get you.
3. 3. Be Consistent: Spelling and pluralization are where so much chaos occurs. Call it user everywhere, not usr, user, and users depending on context. (Or call it users everywhere. Whatever. Be consistent!)
4. 4. Automate Documentation: The docs get generated from the code. Always. Mind you, I’m referring to Reference here (You should have three types of documentation — Context, Examples, and Reference), but if you can, automate the generation of Examples too. And yeah, you’d (not?) be surprised at how often the documentation is either orthogonal, ex post facto, or non-existent.
5. 5. Automated Tests: Comprehensive tests, specifically, around Acceptance. After all, you want to know it’s busted before the customer, right?
6. 6. Instrumentation: Logging, Monitoring, and Alerting. It’s really not that hard anymore, especially with ELK, Prometheus and the ilk being pretty much plug-and-play. Not having these in place is, well, just plain dumb.

That, literally, is it. Make sure that you have these basics down, and while they won’t guarantee success, they sure will ensure that you won’t shoot yourself in the foot!