The Definitive Guide for building REST APIs
Or: how to not write APIs that stink
The “I” from “API” comes from “Interface”, and the great issue of our century in the programming world seems to be the lack of good interfaces. We have good hardware, good programming languages, good network speed to communicate inter-machine processes (inter-continents, too) and good protocols at our hands. But the interfaces design seems to advance like a slug: up two meters, sleep, down one meter, awake, up two meters, sleep, down one meter…
While protocols play the role of the language (and a kind of medium, specially in the “physical” levels of network protocols, for instance), defining how a component should “speak” to another (sorry, saint Dijkstra, I anthropomorphize openly), the interfaces define what a component should say and what to expect as answer.
Now, in real life there's a lot of examples on which we should choose a adequate “interface” for our own communication. A bug reporting process, for example, could be so bad as:
Man, the files is messed up…
Or so good as:
Trying to download a file I find this issue: instead of receiving a 302 status_code with adequade “Location” header, I'm getting a 401 erros. Look:
$ http GET “http://localhost:8000/v1/files/42?_download=1" “Authorization: token $TOKEN”
HTTP/1.1 401 Unauthorized
Connection: keep-alive
Content-Type: text/html; charset=utf-8
Date: Fri, 05 May 2017 21:57:37 GMT
Server: gunicorn/19.6.0
Transfer-Encoding: chunked
Vary: Cookie
Via: 1.1 vegur
X-Frame-Options: SAMEORIGIN
The authorization token is valid, I just checked.
If I try to access the endpoint without _download=1 or with _download=0 everything works as it should (200 status_code).
Notice that the protocol in both cases is right: the English language. The medium can be right, too: a Issue on Github or another bug tracking tool. But the interface is horrible on the first example. It's the trigger for the “bad bug report dance”, whose second step is “what kind of problem are you experiencing?”. That's why the development teams choose more than a protocol (English language?) or the medium (Bug card on Jira?), but also the right way of reporting a bug: that is a kind of interface. If you define a bug report should follow the form of the second example, a report like the first would be rejected, since it does not comply with a series of chosen criteria.
With that in mind, let's talk about interfaces between computer programs, the APIs.
Why APIs stink
1- Because they are “almost” REST. Emphasis on “almost”.
...
Read the complete article here: