The title of this post is stolen from a tweet by Mario Fusco and inspired me to write about it although I’ve touched the subject in earlier posts. The sentence “A good API is not just easy to use but also hard to misuse” just hits the nerve!

Good API - easy to learn & use but hard to misuse

I would add that good API is also easy to learn. If it requires PhD to understand how to get started with your API, you’ve lost the game. In short good API:

Shit will hit the fan

Murphy’s Law says that “Anything that can go wrong will go wrong”. Furthermore Murphy’s law might be extended with Finagle’s law and we end up saying:

Anything that can go wrong, will — at the worst possible moment.

You can’t predict all the ways API consumers use your API. Human mind is wonderful and creative in good and bad. Furthermore the misuse of your API most likely is not intentional, but there’s holes in your documentation or lacking features or limitations which enable misuse.

And if you keep in mind Finagle’s law the shit will hit the fan at the worst moment of your (API provider) life. Life as well as product launch is a gamble, but you should still do some risk management. Perhaps it’s not a good idea to launch new API version right before onboarding couple of whales (big clients) which you have been luring in for past 12 months. Of course you can’t always predict when such things happen, but try to launch product when the risks are at lowest level. Also launching new API version just before the summer vacation is probably not the best idea. You should prepare for the worst after every launch.

Use conventions and defaults

Use conventions for examples with time value formatting. There are things that have been found commonly used practise among the API consumers. With REST APIs, take advantage of status messages. Look at the API Design Guides available online and adopt best practices.

Another good way to limit the amount of misuse is to use default values in parameters. Good example is limit. Your API might be returning a list of items. It should have limit parameter and that should have default value regardless of if the consumer passes the parameter or not. If consumer does not add limit parameter in the query, your API should have default value instead of returning 3 000 000 items. That just makes the query very slow (if not timeout) and useless for the consumer.

Iterative development

You can dream of releasing the perfect API. Here’s a tip - you can’t and you won’t. At least the first release is not perfect no matter what you do and how much you plan and test. You need to get it “80%” ready and then just release it. After that you could send surveys to users every six months and end up eaten by other API providers because your feedback cycle and improvements are too slow.

Instead of asking people what’s wrong, use analytics. A good option is to analyse the usage of your API. Your API management should provide the needed data. It’s up to you if you take advantage of it.

Some more to read from 100 Days DX