RESTful Services - HTTP
The web has been structured around the idea of resources right from the beginning. Web can always be thought of as collection of resources and is often referred to as being resource oriented.
Since all communication on the Web happens over HTTP, REST is intricately tied to it. So, an Understanding of REST requires understanding underlying concepts of HTTP.
Most web applications are built around client- server model. In order to accommodate separation of concerns in client server model, clients and servers must agree upon a set of conventions — a protocol- that dictates all communication between them.
Modern day web applications use the Hypertext Transfer Protocol — HTTP in order to exchange information.
HTTP defines a handful of methods, called as “verbs”, that a client may use in order to describe the type of request being made. Each request is intended to doing specific action on the resource.
eg. create, update, delete, or simply read -> In HTTP this corresponds to making POST, PUT, DELETE and GET requests respectively.
Two additional methods, which are used much less frequently, are the OPTIONS and HEAD methods.
The HTTP GET method is used to **READ** (or retrieve) a representation of a resource.
In the “happy” (or non-error) path, GET returns a representation in XML or JSON and an HTTP response code of 200 (OK).
In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).
According to the design of the HTTP specification, GET requests are used only to read data and not change it. Additionally, GET is idempotent, which means that making multiple identical requests ends up having the same result as a single request.
The POST verb is most-often utilized to **CREATE** new resources.
On successful creation, return HTTP status 201, returning a Location header with a link to the newly-created resource with the 201 HTTP status.
POST is neither safe nor idempotent. It is therefore recommended for non-idempotent resource requests.
Making two identical POST requests will most-likely result in two resources containing the same information.
PUT is most-often utilized for **UPDATE** capabilities,
PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource.
On successful update, return 200 (or 204 if not returning any content in the body) from a PUT.
If using PUT for create, return HTTP status 201 on successful creation.
PUT is not a safe operation, in that it modifies (or creates) state on the server, but it is idempotent. In other words, if you create or update a resource using PUT and then make that same call again, the resource is still there and still has the same state as it did with the first call.
DELETE is pretty easy to understand. It is used to **DELETE** a resource identified by a URI.
On successful deletion, return HTTP status 200 (OK) along with a response body, perhaps the representation of the deleted item (often demands too much bandwidth), or a wrapped response (see Return Values below).
Either that or return HTTP status 204 (NO CONTENT) with no response body. In other words, a 204 status with no body, or the JSEND-style response and HTTP status 200 are the recommended responses.
HTTP-spec-wise, DELETE operations are idempotent. If you DELETE a resource, it’s removed. Repeatedly calling DELETE on that resource ends up the same: the resource is gone.
HTTP Status Codes
Status codes are a useful HTTP construct that provide information to the consumer about the outcome of a request and how to interpret it.
For example, if I were to make a request to retrieve a file from a web server,
I would expect to see a response with the status code describing whether or not my request was completed successfully. If not, the status code would give me a further clue as to why my request failed.
HTTP defines several status codes, each pertaining to a specific scenario. Some of the common series of codes you might encounter are listed here:
Once you understand REST and HTTP, you will be able to write awesome web services in RESTful style.