“Web API” is a confusing term. It can refer to interfaces to be implemented by web software such as browsers, for example the W3C geolocation API, etc. It can also refer to how a web service exposes its data, and it’s in this context that Brian Mulloy has written what I hope will become the bible of REST-based API design. His ebook, entitled Web API Design, is available for free (well, in return for your email address).
As web developers, we want APIs that are easily-understandable and consistent, resulting in less time reading documentation and more time experimenting and being pleasantly surprised that something just works.
At around 30 pages long it’s a quick read but gets straight to the point with concrete advice. Right from the start he emphasises a pragmatic rather than theoretically ideal approach — developers should be able to experiment with and learn the API without the documentation
— and highlights good and bad examples from popular APIs. Here’s a quick summary of some of his recommendations.
- Use two base URLs per resource, e.g.
/dogsand/dogs/1234 - Keep verbs out of your base URLs, unless the data is the result of an action, e.g. “calculate” or “translate”.
- Use HTTP verbs (GET, POST, PUT, DELETE) to operate on the data.
- For clients that don’t support this, make the method an optional parameter, e.g.
/dogs/1234?method=delete - Use plural rather than singular nouns.
- Use concrete rather than abstract names.
- Put complexities after a question mark, e.g.
/dogs?color=red&state=running - Be verbose but simple in your error messages, ideally linking to online docs.
- For specific fields, us a comma-delimted list, e.g.
/dogs?fields=name,color,location - Use “limit” and “offset” for pagination, e.g.
/dogs?limit=25&offset=50 - To specify formats, use the familiar dot notation, e.g.
/dogs/1234.json - Use JSON as the default format, following JavaScript conventions for attribute names.
- Use OAuth 2.0 for authentication.
There seems to be a relative lack of guidance in this field so this book has a good shot at becoming the go-to reference. The result of that would be more consistency between APIs and an easier life for website and app creators. Of course, differences in existing APIs will linger on because of the difficulty in upgrading them once released, but that’s one more reason why it’s important to base an API design on solid guidelines such as these in the first place.
Download the ebook here: offers.apigee.com/web-api-design-ebook/ (no affiliation)
Also, here are a couple of other good resources about designing RESTful APIs:
Daniemon's Blog 