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!

Comments

Post a Comment

Popular posts from this blog

Erlang, Binaries, and Garbage Collection (Sigh)

-
Image
The nice thing about garbage-collection is that it is makes memory management absolutely transparent to you Of course, the above is true right up to the point when it stops being transparent, at which point it does a phase change from nice to clusterf**k of biblical proportions .  There are entire posts, books, and suicide notes that have been written about this, and I have no great desire to add to them, save with the minor comment that paranoia about garbage-collection is still justified , albeit only in the edge-cases for most people. That said, I'll give you that Erlang GC is in many ways much, much better positioned in this regard than, oh, Java, but it still rears up and bites you in the butt when you least expect it. ( More information about Erlang's GC vis-a-vis Java here , and Jesper's truly excellent description of Erlang's GC here ).  A story from the past should serve to illustrate this. Once upon a time, in a magical land far far away - well, Her
Read more

Visualizing Prime Numbers

-
Image
From Jason Davies , we have El Patron de Los Primos , probably one of the coolest prime number visualizer that I've seen.  For every Natural number, he draws a periodic curve that intersects at that number and each of its multiples.  Needless to say, prime numbers are touched by only two curves (itself and 1 ). You can scroll to the right, and move up the prime food change. (The image above is a screen grab.  Go here to see the actual thing)
Read more

Its time to call Bullshit on "Technical Debt"

-
Image
Seriously. You know what " Technical Debt " is, right? Ok, heres the (official?) Wikipedia definition   Technical debt   (also known as   design debt   or   code debt ) is a   neologistic   metaphor referring to the eventual consequences of poor or evolving   software architecture   and   software development   within a   codebase . The debt can be thought of as work that needs to be done before a particular job can be considered complete. As a change is started on a codebase, there is often the need to make other coordinated changes at the same time in other parts of the codebase or documentation. The other required, but uncompleted changes, are considered debt that must be paid at some point in the future. And in this - somewhat purist - sense, " Technical Debt " is absolutely valid. The problem arises in the way it is almost invariably used, viz., as an excuse to not do something. Herewith a simple exercise - the next time you hear someone cite &quo
Read more