In this post I’d like to take a look at REST APIs. REST is a widely used buzzword in the software world and what it currently means is “client communicating with server over HTTP”, but actually the original meaning is slightly more than that. REST is an architectural approach to an API which is supposed to enable large scale distributed computing, and in fact the HTTP protocol is not the only way to implement a REST architecture. It’s quite hard to grasp what REST is all about, and I’m certainly no expert, so YMMV as the saying goes. I’ve just been doing a bit of reading during the break so I thought I’d share some of what I’ve learned.
PS: I still intend to finish the blog post series on setting up a local dev-ops pipeline, just gotten a bit side-tracked recently.
The idea behind REST
REST stands for Representational State Transfer. Just in case you ever get asked that question at gun point in the dead of night, when mugged by a starving Web developer.
The inspiration for REST APIs comes from HTML. When you visit a website with a web browser, it serves HTML (a hypermedia document type) to the web browser, which renders the document for you to view. There are a few nifty features of this process which we’re gonna draw attention to.
- When the website is upgraded – a new page is added or content is moved around – you still access it with the same old browser. i.e. You can make server-side changes, extensive ones even, and the client program doesn’t have to change.
- The user discovers the contents of the website by following links (an HTML link is a simple hypermedia control).
- The user can make changes to the contents of the website by filling in HTML forms (HTML forms are also hypermedia controls).
- The whole website and all its functionality is exposed to the user at the homepage URL of the website. To access the website, the user types the URL into their browser (or follows a link from Google).
If we compare this to the typical relationship between API clients and servers, then code changes on the server frequently will cause the client to break. Also typically the client program has to know up front about the endpoints that are available to it. That doesn’t seem very friendly, compared to how a website works.
Let’s think about this a little bit more. The data from a website is kind of… self-describing. The HTML pages that are served to the browser client contain the control information that tells the user what actions they might like to take. The reason the web browser doesn’t need to be recompiled in order to visit a different URL is because the website itself is telling the browser what controls are available. Also note that the client decides what action to take, not the server. So the server tells the client what available choices there are from the current URL that the client just hit, and the client tells the server what action it would like to take next.
The idea of a REST API is simply that these desirable properties that websites have in relation to web browsers should apply to APIs as well.
- The API should in principle be discoverable from just it’s base URL.
- The API is somehow self-describing, it tells clients about possible actions that they can take when they hit an API URL.
- Clients of the API ideally are not broken when the API is upgraded, though they may need to be upgraded themselves to take advantage of new API functionality.
The question is how to achieve this.
There’s a decent example from a few years ago located here. I’m just gonna steal one quote from there which I feel sums up the way we’re supposed to think about REST APIs:
The key to successful evolution is for consumers of the service to anticipate change by default. Instead of binding directly to resources (e.g. via URI templates), at each step the service provides URIs to named resources with which the consumer can interact. Some of these named resources will not be understood and will be ignored; others will provide known state transitions that the consumer wants to make. Either way this scheme allows for graceful evolution of a service while maintaining compatibility with consumers.
Hypermedia
So ja, there’s a sneaky bit in the quote which you may have noticed, “at each step the service provides URIs to named resources with which the consumer can interact”. That’s what turns the request bodies returned by the server into hypermedia as opposed to just normal JSON data.
The Fielding constraints
REST was originally conceived and proposed as an architecture by Roy Fielding in his dissertation which is heavy reading, but for what it’s worth, here’s the link. He proposed some constraints which make an API qualify as a REST API. ivermectina dor de barriga They’re a bit hard to understand but here they are:
- Identification of resources (this means things that are of value in the domain, such as Customers or Orders or Cats).
- Manipulation of resources through representations (this means not interacting directly with the resources but creating them and updating them via HTTP requests, basically).
- Self descriptive messages (this means that each request must have sufficient information to complete processing of the request by itself, not with reference to previous requests).
- Hypermedia as the engine of application state (this sounds scary but basically means that when you get stuff back from the server it must contain links which tell you what you can do next).
As a way to understand these, there’s something called the Richardson Maturity Model for REST – this description is from Martin Fowler – and I’m gonna steal a quote from there too:
- Level 1 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.
- Level 2 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.
- Level 3 introduces discoverability, providing a way of making a protocol more self-documenting.
Read the link for a deeper step by step understanding of how an API can be turned into a REST API. ivermectina quantos comprimidos tomar por peso There’s also a very nice explanation in the chapter about Fielding’s dissertation in this book.
Final thoughts
I think I can safely say that I’ve never worked on a true REST API. One of the requirements for a REST API is that it should use hypermedia to let the API client know what it can do next, and the APIs I’ve worked on have all been very tightly coupled with the client application. You can do this if you’re writing only ONE client for ONE API, but the true power of APIs is that they can be used for unforeseen things and clever clients can do lots of different things with them. tratamiento de ivermectina A REST API which can evolve and which is more decoupled from the client suddenly gives you lots of flexibility. I’m definitely gonna be thinking about this more in the future.
I didn’t really touch on hypermedia formats in this post, but the book I linked goes into them in depth. They seem tricky to grasp, but potentially very powerful.
REST APIs were kinda a big buzzword maybe 4-5 years ago, now they’re just like… an accepted buzzword. Everyone’s supposed to know what REST means and everyone just pretends that HTTP means REST. Also there are things that I’m not sure how REST covers, like what happens when you can send push notifications to the client.
