Hi everyone
As you may know, throughout my career I’ve ended up doing a lot of integration development. Middleware, APIs, all that kind of stuff. So I thought I would write a quick list of the things you should definitely do to make your API really terrible for other developers to use, so that they put their heads through their desks trying to integrate with it.
Judging from some of the APIs I’ve had the misfortune of integrating with, I thought this was worth writing, for anyone who is building an API.
Obviously this post is humorous or satirical, if you like. Please, for the love of all that is good and sacred in this world, don’t follow these tips!
Tip #1 – Don’t write a darn thing down
No developer likes reading documentation, let alone writing it. So the best tip to make sure that everyone hates your API is to make sure you don’t write a single thing down. Not a thing, nada. Let them guess at how to use it and marvel at your ivory towered genius.
Tip #2 – Make sure that your API is totally inconsistent, especially with documentation
So if you did go to the effort of cobbling together some documentation, and this is critically important, you absolutely must ensure that it is totally out of date. It should be at least 2 major versions behind your developments to keep your job safe.
Also, make sure there are plenty of typos in field names, don’t spell check anything at all; and be sure to use plenty of three letter acronyms that only people within your organisation understand. This will make integration even more surprising.
Top tips for inconsistency include ensuring that you use an absolute minimum of three naming conventions, and at least four different response structures.
Tip #3 – Make sure you use all the wrong terminology
If your API is a straight-up JSON-POST API, which is really simple to use, make sure you throw in a few curve balls. Maybe some GET requests in there, maybe even the occasional PUT or PATCH. It just keeps things entertaining. Parse the API key in the header in some requests, a query string in others and part of the initial request object in the rest.
Also, make sure your account/client/public facing departments refer to your RESTful APIs as Fairy Liquid, and your SOAP APIs as Sleepy ones. This will make sure everyone finds your technical capacity fantastic and will marvel at your technological prowess.
Tip #4 – No version control
If you don’t make sure that your API is versioned, it will keep the developers integrating with it in work; because every time you change it they will have to rapidly drop all of their mission-critical developments to fix any integrations. Be sure to release a patch, break some calls, and then roll it back. Just to punish anybody not using version control on their integrations.
Don’t do anything silly like adding version control, or advanced warning of changes, and definitely don’t even think about doing Beta releases. That just takes the fun out of integration development.
Tip #5 – Throw as many random errors as possible
What you definitely shouldn’t do, under any circumstances, is have a unified and consistent way of handling errors, such as a resource not found or an API key not matching. These errors must be handled differently for every single possible error, on every single possible call.
This is really good for the economy, because it ensures that any developers integrating with your API will have to test every single possibility, against every single call you have. This will keep them in work. You’re doing them a favour, honest.
Why give a JSON error response back, detailing an error code and a human readable message, when a 404 or a 500 will do, that’s what they’re there for! Bonus points if you can throw a 301.
And you’re done.
If you follow these 5 simple rules, you will have a super-awesome-epic API built our of pure ivory, which people will have to pay you to integrate with, because nobody else will know how to.
Then you’ll become like Zuckerberg-cum-Gates rich and be proper leet hacker wizard man (or witch woman).
So there you have it. From someone who’s built, and integrated with, several (probably dozens of) APIs. The top list of things you should definitely never, ever, ever do, if you don’t want to burn in hell for the rest of eternity, stuck in an infinite loop of torture, ridicule and unknown fatal exceptions.
Peace out y’all! 🙂
I’d genuinely love to hear any additional tips you’ve got to build brilliant APIs, and your hilarious anecdotes which are only funny now because you’ve finished the course of therapy and sedatives and recovered from your caffeine addiction enough to laugh at them!