1. Use globally unique identifiers
It’s considered good form to use globally unique strings as entity identifiers, either semantic (i.e. “lungo” for beverage types) or random ones (i.e. UUID-4). It might turn out to be extremely useful if you need to merge data from several sources under single identifier.
In general, we tend to advice using urn-like identifiers, e.g. urn:order:<uuid> (or just order:<uuid>). That helps a lot in dealing with legacy systems with different identifiers attached to the same entity. Namespaces in urns help to understand quickly which identifier is used, and is there a usage mistake.
One important implication…
Before we start talking about the extensible API design, we should discuss the hygienic minimum. A huge number of problems would have never happened if API vendors had payed more attention to marking their area of responsibility.
1. Provide a minimal amount of functionality
At any moment in its lifetime, your API is like an iceberg: it comprises an observable (e.g. documented) part and a hidden one, undocumented. If the API is designed properly, these two parts correspond to each other just like above-water and under-water parts of a real iceberg do, i.e. one to ten. Why so? …
As usual, let’s conceptually define ‘backwards compatibility’ before we start.
Backwards compatibility is a feature of the entire API system to be stable in time. It means the following: the code which developers have written using your API, continues working functionally correctly for a long period of time. There are two important questions to this definition, and two explanations:
- What does ‘functionally correctly’ mean?
It means that the code continues to serve its function, e.g. solve some users’ problem. …
The situation with HTTP status codes demonstrated a disastrous colliding of a well-meaning specification design with a ruthless reality as nothing before. This collision actually comes from three sides.
As we discussed in the Chapter 10, one goal of making errors semantic is to help clients understand, what caused an error. HTTP errors, outlined in the corresponding RFCs (most recently in the RFC 7231), are specifically designed bearing this purpose in mind. Furthermore, the REST architectural constraints, as defined by Fielding, imply that not only end user agents should understand error code, but also every network proxy between a client…
This year, everyone finds their own way to pass the time. I am writing the book, for example. The book on APIs.
Short intro: I’ve been working with APIs for over a decade: developing maps APIs, integration APIs, reviewing W3C specs (see my Linkedin profile for details).
I’ve finished the first section of the book, dedicated exclusively to the API design. You may read it online here: https://twirl.github.io/The-API-Book/docs/API.en.html. There are also .pdf and .epub versions, you may find them on Github. The book is distributed under a CC-BY-BC license, meaning it’s available for free.
To arouse your interest — a…
Sergey Konstantinov
Developing APIs for over a decade
