Skip to content

HTTP APIs: Small, Stable, Readable

What the Heroku HTTP API Design Guide is worth when you hold it up against your own APIs – and why a few resources, a versioning promise and self-explanatory errors achieve more than any framework.

≈ 10 min readSoftwareArchitecture

HTTP APIs: Small, Stable, Readable

An HTTP API that changes its shape every few weeks trains its clients – unfortunately in the wrong direction. After the second break, every client team builds a defensive layer: a mapper that renames fields before the rest of the code gets to see them. A try/catch around every date parser, because the time format has already changed twice. Checks for missing fields, for three different error formats, for status codes that sometimes mean one thing and sometimes another. After half a year, half of the client consists of code that doesn’t model the domain but distrust. And because every team invents this layer for itself, in the end it exists four times, in four variants, with four different bugs.

So the costs don’t arise where the API is built, but spread across everyone who uses it. That is what makes them so easy to overlook.

In May, Heroku published its HTTP API Design Guide – a slim document on GitHub, distilled from the work on the Heroku Platform API. I forked the repository at the end of May and have since held it up, point by point, against APIs that I maintain myself or see in reviews. I wouldn’t sign off on all of it. But the basic attitude matches pretty closely what I have found to hold up in my own projects: a good HTTP API is small, stable and readable. Everything else is accessories.

Small: a resource has to earn its place#

The guide doesn’t say it literally, but it is between all the lines: few resources, with consistent conventions. Resource names in the plural (/orders, not /order and certainly not /getOrders), paths as flat as possible, IDs as lowercase UUIDs, created_at and updated_at on every resource – without anyone having to ask for them.

That sounds trivial, but it isn’t. In a project at the beginning of the year, we took over an API that had more than sixty endpoints – for a domain that was fully described by about ten resources. The rest were convenience endpoints: /orders/search, /orders/latest, /ordersWithCustomer, each created because a client team needed a particular view and the fastest route was a new endpoint. Each of these endpoints had its own response format, its own idea of pagination and its own lifespan. None of them could be removed, because nobody knew who was still calling it.

Since then, my rule is: an endpoint is a liability, not a feature. Every resource I publish, I have to carry for years. So before every new path, I first ask whether the use case can be expressed through an existing resource plus query parameters. Most of the time the answer is yes – and the API stays small enough for a new developer to understand it in a morning.

This is the normal case that everything else should relate to:

GET /orders/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "state": "confirmed",
  "total": 4990,
  "currency": "EUR",
  "created_at": "2014-06-20T08:30:00Z",
  "updated_at": "2014-06-21T10:15:00Z"
}

Nothing about it is spectacular. That is exactly the point: once you have seen this one response, you can guess the shape of every other resource in the API. This predictability is the actual product.

Readable: the error explains itself#

The part of the guide I adopted immediately is the error format. Heroku proposes the same body for every error: a machine-readable id, a human-readable message and a url that points to further documentation.

{
  "id": "rate_limit",
  "message": "Account reached its API rate limit.",
  "url": "https://docs.example.com/rate-limits"
}

Why this convinces me: it serves both readers at once. The client code branches on the id without parsing strings. The person reading the log at two in the morning understands the message without opening the docs. And the url ends the guesswork when they do have to open them.

The contrast with practice is stark. In reviews, I have come across the same collection again and again: sometimes an HTML error text from the proxy, sometimes {"error": true}, sometimes a stack trace in plain text, sometimes status 200 with an error message in the body. Each of these variants forces the client to bolt another special case onto its defensive layer – which brings us back to the beginning.

With Express 4, which has been out since April, a uniform error format can be enforced with very little code. The core is a small factory for error objects and exactly one central error handler, registered as the last middleware:

// errors.js - one error shape for the whole API
function apiError(status, id, message, url) {
  var err = new Error(message);
  err.status = status;
  err.id = id;
  err.url = url;
  return err;
}

app.get('/orders/:id', function (req, res, next) {
  store.findOrder(req.params.id, function (err, order) {
    if (err) { return next(err); }
    if (!order) {
      return next(apiError(404, 'order_not_found',
        'No order exists with the given id.',
        'https://docs.example.com/errors#order_not_found'));
    }
    res.json(order);
  });
});

// registered last, catches everything
app.use(function (err, req, res, next) {
  res.status(err.status || 500).json({
    id: err.id || 'internal_error',
    message: err.message || 'An unexpected error occurred.',
    url: err.url || 'https://docs.example.com/errors'
  });
});

The side effect I hadn’t expected: the list of error IDs becomes a catalog of the domain. When it contains order_not_found, order_already_shipped and payment_declined, it reads like a summary of the domain. An API whose errors read like this needs much less prose documentation – the URL tells the domain story for the good cases, the error ID tells it for the bad ones.

Stable: versioning is a promise, not a header#

On versioning, I only half agree with the guide. Heroku recommends requesting the version via the Accept header – Accept: application/vnd.heroku+json; version=3 – and rejecting requests without an explicit version. That is the cleanest form: the URL identifies the resource, the header negotiates the representation. That is how HTTP was meant to be.

But in the projects I know, the version in the URL almost always wins, that is, /v1/orders. And not out of ignorance, but for solid reasons. A curl call to reproduce a bug doesn’t need an extra header. The access log shows at a glance which version a client is using – important when you want to know whether /v1 can finally be switched off. Proxies and routers can split by path prefix without inspecting headers. And in the browser, you can look at a GET response without any tool. The Accept header is more elegant; the URL is more honest about the everyday reality of operations and debugging. I use both and wouldn’t push the header variant on any team that loves its logs today.

More important than how the version number travels is something else anyway: what the version promises. A version number is the commitment that nothing breaks within that version. In concrete terms, for me that means:

  • New fields and new resources can be added at any time – clients have to ignore what they don’t know.
  • Existing fields change neither name nor type nor meaning.
  • Error IDs and status codes for existing cases stay as they are.
  • If any of these is violated, there is a new version – and the old one keeps running until it can be shown that nobody calls it anymore.

This decision logic is small enough for a diagram, and by now I actually put it up on the wall when a team is discussing a change:

flowchart TD
  A[Change to the API] --> B{Only additive?<br/>New fields, new resources}
  B -- yes --> C[Same version<br/>clients keep running unchanged]
  B -- no --> D{Does the name, type or<br/>meaning of something existing change?}
  D -- no --> C
  D -- yes --> E[New version<br/>old version keeps running<br/>until the logs declare it dead]

The uncomfortable part is in the last box. Announcing a new version is cheap; keeping the old one alive is the real work. If you don’t want to keep the promise, you’d better not hand out a version number at all – a /v1 that still breaks every two months is worse than none, because it signals a reliability that doesn’t exist.

Timestamps and pagination – the underestimated details#

Two points in the guide look like footnotes at first glance, but have saved me more hours of debugging than some architecture decisions.

First: times exclusively as ISO 8601 in UTC, that is, 2014-06-20T08:30:00Z. In a legacy system, I once had three time formats in the same API – Unix timestamps in seconds, Unix timestamps in milliseconds and a German date format with dots. The bug that resulted was a classic: a client interpreted seconds as milliseconds, and suddenly all orders were in January 1970. Since everything has consistently been ISO 8601 with a Z at the end, this entire class of bugs has disappeared. The format is sortable, unambiguous, and every parser in the world knows it.

Second: pagination. The guide refers to Heroku’s Range header – the client requests a slice with Range, the server responds with 206 Partial Content and names the key for the next page in the Next-Range header:

curl -i https://api.example.com/orders \
  -H "Range: id 01234567-89ab-cdef-0123-456789abcdef..; max=200"

# HTTP/1.1 206 Partial Content
# Content-Range: id 01234567-...;
# Next-Range: id 89abcdef-...; max=200

Technically, I like one thing about it above all: it is cursor pagination. The client pages forward from a key, not from an offset – and therefore gets no duplicates or gaps when new records are created between two pages. The classic ?page=3 has exactly this problem, and it only shows up in production when the data changes fast enough.

Still, on the transport, I am again more pragmatic than the guide. Range headers for something other than bytes are unusual, many HTTP libraries make access to response headers more awkward than necessary, and in the team you have to explain the convention to everyone anew. In my own APIs, I have ended up with cursor pagination via query parameters – ?limit=200&after=<id> – with a next link in the body. The same property, more ordinary mechanics. I adopt the guide’s idea, not its syntax.

That, by the way, is exactly my relationship with the document as a whole. It is a collection of decisions that a team made for its platform and justified publicly – not a standard, not a law. Its value lies in forcing you, while reading, to take a stand for each of your own APIs: adopt, deviate, but never again “we never thought about that”.

What I take away#

If you build an HTTP API in 2014, the format problem is basically solved – JSON has won, the verbs are in the RFC, and with HAL and JSON Schema there are lively discussions about how much hypermedia an API should take. The real problem is a social one: an API is a promise to people whose code you will never see. Small, stable and readable are the three properties that make this promise keepable. Small, so you can keep track of it. Stable, so you can trust it. Readable, so you can understand it without an interpreter.

The Heroku guide is the best checklist for this that I have come across so far – precisely because it is so short and because a real platform is clearly behind every point. My fork has been in my GitHub account since the end of May, and the most useful exercise wasn’t reading it, but mirroring it: putting each of my own APIs next to it and noting, point by point, where it deviates and whether there is a reason for it. For me, two deliberate deviations remained – version in the URL, pagination via query parameters – and an uncomfortably long list of places where the deviation was simply sloppiness. I am working through that list right now. The clients won’t notice, and that is exactly how you know it is the right work.

Further reading#

Revised and translated from German with the help of AI.