Web API Design – a definitive guide

Cover of Web API Design book“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. /dogs and /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:

2 thoughts on “Web API Design – a definitive guide

  1. karl

    Note that the book is Web API design, and not RESTful API design. :) So I was induce into errors when reading the post and specifically looking at the list which is not about RESTful, but the classical HTTP “good practices.” :) I disagree with some but it’s ok. It’s just design :)

    What is interesting for me in the play of words and the pragmatic outcomes is that we refer to words as totems for validation but recommend something else, instead of just carving a practice for its own. The RESTful (or HATEOAS) design is useful when you are looking for a market of interoperable APIs. Currently, most of the shops out there don’t do that—at all—. They all expose their own APIs to the world expecting people to consume their APIs, not to make an interoperable protocol for exchanging data. I guess it is one of the issues. The essential principle behind RESTful is a follow your nose principles, aka the client is able to discover the API as it browses it, exactly like a human do not need an external guide to explore a Web site, we just click on links, and we hopefully 😉 get the context of the next action.

    Here in this page, There is a form for commenting, which contains instructions and guidance which helps me reach the next step. There’s also a guide on what I can do and what I can not. Such as the “You may use” etc. :)

    « Brian Mulloy has written what I hope will become the bible of REST-based API design. » Nooo 😉 It can’t. it’s not REST-based. In the book page, for example, there is “Versioning is essential” :) which is exactly against some of the guidances of REST. It doesn’t mean it’s not a good book with interesting recommendation, but it’s Web API, not REST API.

    I recommend reading the post REST APIs must be hypertext-driven with *all* the comments and also the site by Amundsen.

    1. Daniel Post author

      Thanks for the comment, Karl.

      I’m not sure I agree with you 100% but I’ve removed the “RESTful” from the title. I had included it because I wanted to avoid confusion between the API structure mentioned in the book and other Web APIs (i.e. JavaScript APIs) that developers may be familiar with.

      Anyway, your additional explanation of RESTful design is helpful — thank you.


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>