There seems to be a big emphasis on using REST these days. Where REST easily becomes a synonym with HTTP. It is not, REST is an architectural style - a set of rules. However there is a lot of confusion on this when you look it up. You can easily use the HTTP protocol without applying the principles of REST (I am not advising you to do this).
Rest and HTTP
So HTTP is just a protocol that can be used in many ways. REST can be applied to this to create a standard way of implementing your HTTP endpoints. If you are using the full palette of HTTP verbs and creating resource based URLs you are probably writing RESTful APIs. But what does this mean? Here are some examples (none of the url examples actually exist):
Often you will find that RESTful APIs are versioned. In the below I have created an API called someapi with the version v1. This is the base url for this (REST) API. The next item, the persons part is the resource that I wish to interact with (there is a lot of debate on whether this should be plural or not).
In order to get a specific person I should write something along the lines of:
http://peterdaugaardrasmussen/someapi/v1/persons/peterrasmussen
Now the above would be a great URL for getting the person “peterrasmussen” (definitely not a unique name). Using HTTP this would be done using the GET verb. The same url could be used with delete, put (update and create) and many other "actions'' (http verbs).
What would not be the REST way? The below is a great is example of something bad:
http://peterdaugaardrasmussen/someapi/v1/persons?action=delete&id=peterrasmussen
What is the verb in the above? It could be any, I have seen deletes being implemented using the get verb. Which is very wrong as get should not change anything on the server side - get is a "safe action". In the above the consumer of your API would have to guess how to set the action and id, instead of using a standardised way.
Other important aspects
Another important factor for restful services is that the requests must be independent and idempotent. Independent means that the second request should not rely on the first one. idempotent means that if you repeat the request the same result will happen. Sending a post twice will create two resources. Sending an update on a resource twice will update it twice. Same result.
The big advantage and the point of using REST is that the API is easier to understand. If you have a resource that has not yet been created, then sending a put or post will likely create it. A get will fetch it and Sending a delete will delete it. All of this the developer can easily deduce due to it following the standard of REST.
Summary
REST
- You provide an action (get) on a resource (/person)
- Stateless
- Requests are idempotent
- Requests are independent
In HTTP this translates to
- URLs are resource oriented
- Make use of HTTP verbs
I often say that REST is just HTTP with nice URLs and good use of verbs. That is not entirely true, but close. If your APIs do not fit the above I would not call them restful. Whether that is a bad thing or not is up to you.
That was my post on REST vs HTTP, let me know if you disagree down in the comments below!