The idea of building your website services in a RESTful way consists on using the HTTP protocol to determine the Action you are going to perform instead than some Action name on the URL. This way, we can build APIs that are more standarized and easy to sue for everyone.
But… what is REST?
REST is an abbreviation for “Representational State Transfer” and, as its name points out, it’s an “idea” (let’s call it idea for now) to transfer the State of an object through a Network. But that idea is based on the HTTP protocol, in fact REST was born as a way of using HTTP properly, some type of “HTTP good practices”, which we can call “an architectural style”, or architectural pattern if you prefer.
The point is… HTTP is so impressively powerful and flexible, so much that even on its day many years ago there didn’t seem to be any standard of how to use it, so REST was born as a way of standardizing that a bit.
And what is a RESTful service?
A RESTful service is a service built following the REST idea/principles. Which, by the way, is not that simple. Have in mind that REST lays over HTTP, so many people will use HTTP and then just because it looks similar to REST (as it uses the HTTP protocol) consider it RESTful enough. MEEEEC.
But how can it be RESTful then?
Oh well… the truth is that the developers community is still trying to figure out what is the best way of using the HTTP protocol, building new websites, and even using the REST principles. It isn’t then a precise pattern (in fact, there’s probably no pattern that’s precise, that’s why they are patterns) but it has some clear guidelines:
First of all, the main idea consists on using the HTTP protocol verbs, these are: POST, GET, PUT, DELETE, and many more, but REST community seems to contain itself to CRUD (Create, Retrieve, Update, Delete). This way, instead of having so many Action names written on an API: “UpdateUser, DeleteUser, CreateUser”… and its possible variants: AddUser or CreateUser? DeleteUser or RemoveUser? You just use the VERB, that’s a standard, a PUT is a PUT and a DELETE is a DELETE. As HTTP is already defined, no discussions over here.
Secondly, REST is about transfering object states, resources. So the main idea is that we will call something like example.com/Users, and help ourselves with the verb and the Request Body to send the object. So that we focus on the resource and organize the API in such way, making it easy for anyone to know that the URL example.com/Users/ has 4 “actions” (the CRUD verbs) and having a very good idea of how to use the API without needing to read any spec. That’s a good practice!
Let’s see some examples:
If I want to retrieve a user:
[GET] example.com/Users/{id}
If I want to remove a user:
[DELETE] example.com/Users/{id}
If I want to add a new user:
[POST] example.com/Users/
PostBody: {UserObject}
Or to update that user:
[PUT] example.com/Users/
PostBody: {UserObject}
Where UserObject could be in JSON or XML format. And yes, there seems to be an agreement on the difference between POST and PUT.
When updating an object though, the idea is that you post the full object on a request using PUT and then the server will just update the object with the new values. But of course, you may be wondering, what if an object is so complex or big that I don’t want to send a full one each time I want to update a boolean? No worries, there’s no need to send the full object actually, you can just send the object Id and the fields you want to update, it will be up to you on the server side to determine what the requester is trying to do, but I tell you now that using different models can help a lot with this.
If you want to know more, you can read some more good practices about making a RESTful service.
