API do’s and dont’s
January 27, 2021
written by
Joren Mathews
Developers have all experienced APIs that make things harder than they need to be and the accompanying ‘help’ docs that make things even more complicated. As devs, we already have a reputation for our poor communication skills, so why encourage this heinous falsehood with poor documentation and error messages? We get that you needed proof of concept but once you get a dozen people using your API, spend some money and hire a technical writer.
Here’s a (very partial) list of Do’s and Dont’s that will make developers happy and save clients money.
Do:
Provide working examples for basic functionality.
Code snippets for a selection of popular languages that work and require less effort beyond copy/paste. A good example is Send Grid, with examples for many languages, and even different request libraries available for those languages.
Provide useful error messages.
If a required parameter is missing, or the data type is wrong, then say so. Don’t just return “Something went wrong ¯\_(ツ)_/¯”. If you knew enough to reject the request, you knew enough to say why.
Don’t:
Require oauth or anything else more complicated than an API key unless strictly necessary.
I’ve never implemented an API where an API key wasn’t sufficient security for server-to-server implementations. Calling out Constant Contact on this one, which has cost hours of time with authentication boilerplate and issues to add an email to a list of emails.
What it takes to authenticate an oauth based API request:
What it takes to authenticate an API key based request:
Write a book for your documentation.
80/20 rule applies. 80% of your API usage will be the basic use of core functionality. Make that clear and concise while making the advanced usage and edge cases require a bit more digging. If it’s not needed 80% of the time, why are you setting it up as a bigger issue than it needs to be?
In sum, it’s pretty simple. Give good examples to help people use your tools. Don’t use a sledgehammer when a simple tap of a hammer will do with authorizations. You need to approach your documentation the same way you approach any user flow. We’re going to keep this list open for more API transgressions and kudos, so check back for updates to see who has been naughty or nice.