✏️ Pragmatic Web API design

Csaba Palfi, Mar 2013

I worked on quite a few public and internal REST APIs both building and consuming them. REST is more of an architectural style than a well-defined framework. It's sometimes not easy to make sure everyone is on the same page when you talk about REST.

Reading Roy Fielding's famous dissertation helps you understand the philosophy (especially chapter 5) and it's a wonderful piece of work. I published an epub version on github (in case you would like to read it on your mobile) or you can grab the pdf or read in HTML here.

At the same time it's definitely worth having a look at what works in the wild and how others build web APIs. That's exactly what Apigee did before publishing a short ebook with their suggestions for good pragmatic web API design and I think they're straight to the point in most cases.

It's mainly addressed to companies building public APIs but lot of the sections are also relevant for internal APIs. They highlight good and bad examples from public APIs by companies like Facebook and Twitter.

Let me recollect the essence of the Apigee Web Api Design ebook here but please feel free to grab the original ebook for more details and the examples.


Nouns are good, verbs are bad

Plural nouns and concrete names




General logic for parameters

Partial response


What about responses that don't involve resources?

Supporting multiple formats

What about attribute names?

Tips for search

Global search

Scoped search

Formatted results

Consolidate API requests in one subdomain

Tips for handling exceptional behaviour

clients unable to handle non-200 reponse properly

client supports limited HTTP methods


Chatty APIs

RESTful APIs can end-up being a chatty easily

Complement with an SDK

Reasons to consider and SDK:

The API facade pattern

When creating an API for an array of complementary systems:


The API facade pattern

  1. Design the ideal API - design the URLs, request parameters and responses, payloads, headers, query parameters, and so on. The API design should be self-consistent.
  2. Implement the design with data stubs. This allows application developers to use your API and give you feedback even before your API is connected to internal systems.
  3. Mediate or integrate between the façade and the systems