There was a time when REST was a revolution. The premise of a new world where SOAP problems would be washed away. (I went on a slippery road with that play on words, didn’t I?) REST is now a defacto standard that is starting to lose its momentum (or maybe has already lost a lot of it). For some of us, it still holds a particular place in our mind, our first true love. This journey when we discovered interoperability that worked. For others, starting out in development, it represents a standard that doesn’t belong to the vanguard anymore, something from the past, a legacy, something they don’t want to invest their time in — it’s just there.
Yes, there are other solutions today aside from web services in REST and JSON, lots of them. There are even multiple REST comprehensions out there, and I already know that by writing this article, I might trigger a nerd war about what is an authentic REST architecture. People will start to raise Roy Fielding’s 2000 dissertation as proof. And to be honest, I’ve done my share of fighting over such ideas, but that time has passed. After having worked for so many years in the industry, I consider myself as just a developer, a regular developer. So, I won’t pretend that I write the truth. I’ll just write what I’ve done and seen for the past years, in practice, at work, out there.
REST 101
If I needed to explain REST to my relatives in just one sentence, I’d say, “It’s a way of making applications talk together,” no more, no less. If I wanted to go further (knowing I’d lost them in the process), I’d add, “It’s a way of structuring the dialogue between multiple applications.” Just like an orchestra conductor expects the first violin to be on his left and the cello to be on his right; as a developer, you expect a REST architecture to follow some guidelines to find what you’re looking for quickly.
When you write an application, your goal is to solve your user’s problem, whether they’re bored (so you write games), overwhelmed (so you write reminders, calendars, to-do lists), creative (well, you got the idea), and so on. There are times when the application itself will have its own problems to solve (for example, getting the GPS coordinates from an address). There are other times when the application will be able to solve other applications’ problems (for example, you’ve written a a grammar checker, a word count, a dictionary or a thesaurus). So at one point or another, you might want your application to ask for a service from another one, or you might entice another application to get its answers from yours. There are many methods at your disposal to enable the communication between two different (and distant) applications, and there are even books dedicated to this matter. REST is one of them.
REST is a combination of technologies and standards put together. When we say REST, we often have in mind the following:
- HTTP,
- JSON,
- And… that’s it!
Could have been worse right?
So at its root, that’s all REST is.
HTTP, this thing everyone uses
When I tell my friends (well, those who don’t work in IT) that they use an HTTP client almost every day, and that they even have a favorite one, they are often incredulous.
“Yeah, sure, I have a preference for this whatever client you’re talking about.” And they’re often shocked when they realize that they do have a preference because a regular web browser is an HTTP client. What also amazes them (even more) is what’s going on under the hood, when I show them that they can consult the code behind the pages. This internet browser is an HTTP client whose sole purpose is to transform HTML, CSS and Javascript into beautiful pages (or just pages if I were the designer).
So, in a way, everyone knows about web services — Your machine (the client) talks to another machine (the server) using HTTP (the protocol), so the server sends HTML (the response) displayed in your browser window (the feature of your application).
Yes, REST uses the exact same protocol as your browser. But before we talk about the differences, let’s talk about the response itself…
JSON, a humanly readable message
When computers exchange information, they don’t expect humans to read their raw dialogue. This assumption has its advantages because the human brain is not capable of understanding binary files. Surprisingly, this fantastic non-artificial intelligence that is our brain cannot interpret the message if it’s not expressed using chains of characters (how primary). But humans, these stubborn beings, sometimes find it convenient to be able to read the exchange, and JSON is a text format that humans (even beginners) can understand. It’s also one of the most easily readable ones.
Let’s say I have access to a web service available at /service/reservations where I can see the reservations made to my favorite restaurant.
The response should contain the reservation dates, times, and numbers. And it’s precisely what you would find in a typical JSON response.
If you told me that only IT professionals were able to understand this JSON response, I’d be surprised…or I would know that you partied too hard yesterday.
And that’s it
Yes, that’s truly the core of REST — HTTP and JSON. But have we talked about everything yet? Not even close. So let’s keep diving into the subject.
So, web services…what can I do with them?
Let’s go back to the purpose. When a user, through an application, deals with a system, it’s either for querying for its current state, or for updating its current state. You can think hard and try to find different use cases, but you won’t (ok, you won’t, if you agree with me that computing a value falls into the category of querying for the current state that is the knowledge).
Let’s now have a closer look at HTTP. For now, all we did was agree on the fact that your browser was an HTTP client. We’ve also agreed that this browser was dedicated to requesting for the server’s content (the internet). If I was browsing Wikipedia, I could consult a wide variety of pages, answering an even wider variety of questions — what a computer is, what temperature I can expect in Paris in December, who Superman is and what the Matrix is (even if we might not have the full answer for this one). The response would be expressed in natural language and designed with HTML / CSS.
But what if I wanted to contribute? What if I wanted to add my own piece of knowledge to the system? I’d look for a button to switch to editing mode. I’d fix a typo, add a bit of information (something reliable, like that “Superman is the strongest super-hero, no discussion”), add a reference, or rephrase something I found tricky to understand. Once done, I’d want to send it to Wikipedia, and my browser would use the same HTTP protocol to communicate with the server, but would use a different verb.
The HTTP Grammar
Yes, verbs.
Let’s go back to our restaurant and our reservations. Up to this point, what we’ve done is query the system state — What are the known reservations? To send our request, we’ve used our browser. The browser used HTTP and the verb “GET.” (Like, “GET this information for me,” quite easy to remember.)
As we saw before, we’ll also need to update the system, like adding a reservation, changing the time or number of guests for a given reservation, or simply deleting our reservation.
And REST does have the corresponding verbs:
- POST: Create a resource,
- PUT: Update a resource,
- DELETE: Delete a resource,
- PATCH: Update properties of a resource,
- GET: Read a resource.
But before we can see them in action, we need to talk about the last piece of the puzzle.
Follow the path
Collections
If the verb determines the action, the path (the URL) defines the subject. When we GET /service/reservations, we deal with the whole reservation collection. As a consequence, if we wanted to add a reservation, we would POST to that same URL (the collection) along with a JSON message representing the new reservation.
#Request
POST /service/reservations
With the following sent data
If we consulted the collection right after the insertion, we would get
#Request
GET /service/reservations
#Response
Note that the system has added reservation IDs to the collection items.
A single element
But what if we’d like to get a specific element in that collection? Like, the R3 reservation we’ve just made?
We would specify the element ID, right at the end of the path, like below.
#Request
GET /service/reservations/R3
#Response
Notice that the response is now a single element (starts with the opening curling brace), and no longer a collection of elements (that started with the opening bracket).
We haven’t talked about updating a record?
Yes, let’s do this.
To update a record, we have two choices at our disposal:
- PUT (to update the whole document)
- PATCH (to update some information)
Let’s start by updating the whole record. The request will look like the one we sent for the creation.
#Request
PUT /service/reservations/R3
Now, let’s suppose we only want to change one of the properties of our reservation. We’ll use the PATCH verb on the same record (same path). When using PATCH, we can send a partial JSON message. Here is what we’d send to change the time we’d like to arrive.
#Request
PATCH /service/reservations/R3
#Sent data
With this record, the time of the reservation will be updated, but the rest of the data will stay untouched.
And one verb to delete them
And last, to cancel our reservation (deleting it), we’d do
#Request
DELETE /service/reservations/R3
This is your first stop
So we’ve gone through the core concepts of a REST architecture. If you’re new to development, a project manager, a business analyst or anyone that has to be in touch with IT but not involved in the development and not involved in fine-grained conceptions of those kinds of services, it should be sufficient knowledge to understand people modeling such architectures.
Quick Recap
We can define REST as a way to enable communication between systems. It stands on HTTP and (for the most part) JSON. We expose services through resources that describe the content of the system thanks to meaningful URLs (collections /resources/, or individual elements /resources/element-id). To manipulate the system, the client uses HTTP verbs on these resources so it can CRUD them (Create, Read, Update and Delete).
If you have any questions, please don’t hesitate to ask in the comments, I’ll do my best to answer. Also, don’t forget that this is the first in a more extended series, and we’ll soon dive deeper into the world of REST!
Top comments (0)