Over a million developers have joined DZone.

The Journey to Craft Perfect APIs

DZone 's Guide to

The Journey to Craft Perfect APIs

· Java Zone ·
Free Resource

Trying to be a perfect in a never taught art

Several years ago our projects were lone islands, doing everything inside, sometimes communicating via database or from time to time via XML and Web Service. Rarely did developers have to consume sophisticated API and almost never did we have to create one. And because there was no need to write that, no one was teaching how to do it properly.

Nowadays things look completely different, we live in the era of public APIs: Twitter, Facebook, microservices, nanoservices, two-line-services. Everything should have perfect REST API: well thought out, nicely designed and easy to use. But how to achieve these goals? This is a main subject of short book “Web API Design – Crafting Interfaces that Developers Love” byBrian Mulloy available for free on ApiGee site.

What is this book about

I am not going to write full abstract because this book is extremely short (and again, free), only 36 pages so you can read it in two evenings. It is showing good practices when creating REST APIs with many real-life examples taken from such prominent companies as Google, LinkedIn, Facebook and Netflix.

We can learn that:

  • nouns should be used for naming instead of verbs

  • we should not have more than two endpoints per resource

  • errors indication should be done via HTTP Statuses (we can start with three: 200 – ok, 400 – request was not ok, 500 – something went wrong)

  • but with human readable error messages that can be displayed when necessary

  • API version should be mandatory

  • place where version should be stored is not yet standardised, there are two approaches: url or request headers.

So if you are in the “chatty” project communicating with others via REST or trying to make your API as usable for other developers as possible, you should really, really consider reading this paper. Short, concise and straight to the point.

PS: Many thanks to the Rafał Remisiewicz for pushing me to reading this book and for being “Certified REST API designer” in our project for several months when we were working together :)


Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}