No other technology in the IT history generated as many fierce debates as REST did. The most remarkable thing is that disputants usually demonstrate totally no understanding of the subject under discussion.
Let’s start with the very beginning. In 2000 Roy Fielding, one of the HTTP and URI specs authors, defended his doctoral dissertation on ‘Architectural Styles and the Design of Network-based Software Architectures’. Fifth chapter of this dissertation is ‘Representational State Transfer (REST)’. It might be found there.
As anyone may ascertain upon reading this chapter, it holds quite an abstract overview of distributed network architecture, which is bound…
NB: this is an expanded and updated compilation of two previous publications.
When all entities, their responsibilities, and relations to each other are defined, we proceed to developing the API itself. We are to describe the objects, fields, methods, and functions nomenclature in details. In this chapter we’re giving purely practical advice on making APIs usable and understandable.
Important assertion at number 0:
0. Rules are just generalizations
Rules are not to be applied unconditionally. They are not making thinking redundant. Every rule has a rational reason to exist. …
NB: this is a draft of two new chapters for ‘The API Book’ I’m writing.
Strong coupling and related problems
In previous chapters we tried to outline theoretical rules and principles, and illustrate them with practical examples. However, understanding principles of change-proof API design requires practice like nothing before. An ability to anticipate future growth problems comes from a handful of grave mistakes once made. One cannot foresee everything, but can elaborate a certain technical intuition.
So in following chapters we will try to probe our study API from the previous Section, testing its robustness from every possible viewpoint, thus carrying out some ‘variational analysis’…
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
The API Guy
