small things that make apis a little bit better

Over the years, I’ve implemented clients for a fair number of APIs.

I’ve compiled a list of things that have made my life better. Most of these ideas are not about API design or architecture. They are mostly about the small stuff that you, as the creator of an API, can make that will make implementatio of clients a little bit less painful.

• Make tables downloadable, parseable

You have a beautiful autogenerated documentation that has a bunch of tables with list of error codes, statuses, etc. Make those lists downloadable as CSV, JSON, or whatever parseable format you wish. Never, ever have the canonical version of those tables/lists as PDFs.

This also applies to sample responses.

• Add an echo/test method

Sometimes you just need to test if the API is alive and well. And you might not have the docs at hand or, due to the nature of the API, calling a method for just testing and endpoint might be complicated. Having an ‘echo’ function that can be called via curl helps a lot in these cases.

• Include examples of your top use cases

Not all API methods are equal. Most of the people will only have to implement a certain amount of methods. And those methods might be called in a specific order. Include pseudocode of the top use cases in your documentation.

• Be clear about times

Very, very rarely do I get to see documentation that states expected responses times. You don’t have to specify a number of seconds as a SLA. Just a hint that this or that specific function might take longer than one might expect.

• Include an error/status description

The person grepping logs when things are not working might not be the on that implemented the client for the API. Having a textual description of the status or error code that can be understood by that person is very useful and can help fix things faster.

• Hide your errors, but give enough data for feedback

I’ve seen APIs that have error codes for situations that are relevant only to the team behind the API.

Errors such as “db error”, “misconfigured user”, “lock timeout” are of no concern to the users of the API. Label those differently and add note in the error description telling the user to contact support.

• Include step by step raw data for complex transformations

By whatever reason you need people to concat, hash and encrypt some data in a series of steps? You have an algorithm that needs the data mangled in a specific way? Add sample data and how it gets transformed by each step. Not all languages have libraries that work in the same way or receive the same parameters. Having a way to incrementally replicate complicated steps helps a lot to people that have to code some stuff from scratch.

• List common gotchas

What is the hardest part of implementing your API? What people ask most about? Add that as a note in the relevant function in your documentation. Or whetever it fits best.

• Let users know how you can be reached

Most APIs documentation have everything except a way to contact the correct people for technical questions regarding the API. Sometimes you end up searching the website for a contact form or write an email to support@whatever and eventually you get in contact with the people that can answer questions about the API. If you can, please describe how people can get in touch with the people that can actually answer questions about the API.