REST is an architectural pattern where two or more applications exchange resources among themselves through a set of operations on these resources. The resources are sets of data types that all the involved applications, such as products, customers, and so on, know about. For example, a client application can either ask a server application to give it a list of all the resources of a given kind that it stores, or ask the server to register a new instance of a given resource in its database. All such operations are communicated only by using the standard HTTP protocol, which makes the process both intuitive and easy to implement.
At the heart of the RESTful communication are the common HTTP verbs—GET, POST, PUT, and DELETE. In terms of the popular CRUD (Create/Read/Update/Delete) acronym, C corresponds to POST, R to GET, U to PUT, and finally D to, well, DELETE. If you are familiar with HTTP, you will already know that these verbs represent different request types sent between two HTTP-speaking applications. For example, when you type www.google.com in the URL field of your browser and press the Enter key, the browser will issue a GET request to the server the URL is bound to, asking it to return whatever data is located at server. Typically, this data is in a standard format such as HTML, XML, or JSON. In the same way, when you fill out a form on a webpage and press the submit button (or its equivalent), a request is sent to the server through a POST request, which carries the request data that you entered for the server to process.
As mentioned before, REST functions by using these verbs to communicate operations on various resources that the involved parties know about. For example, in our case, we may want to tell a server the following by using the RESTful requests:
- Fetch all the products that are available on the server (the verb is
GET) - Fetch the product with an ID of
abcd1234(the verb isGET) - Place a new order with a product named
abcd1234for a customer with an ID ofxyz456(the verb isPOST) - Update the price of the product with an ID of
abcd1234to 500 million dollars (the verb isPUT) - Delete the product with an ID of
abcd1234since nobody is buying it anymore (the verb isDELETE)
By convention, REST uses the following common base URL structure for requests operating on a given resource (elements in the brackets are optional):
http://<domain>/[api name]/[api version]/<resource>
For our product example, a RESTful base URL for this resource is as follows:
http://myserver.com/myapi/v1/products
In the following section, we will demonstrate how such actions are carried out in practice using the HTTP verbs.
In the context of REST, a GET request always indicates a retrieval operation. Thus, we say that the GET requests are the only non-mutating ones among the common verbs, since they do not change the state of the associated resource on the server.
In REST, there are two standard GET operations that any API should ideally implement:
The following are the key features of the GET all operation:
- It sends a blank GET request to the base URL for the resource
- It returns all the resources of a given type
- An example of resources that are given by the GET all operation is
http://myserver.com/myapi/v1/products.
The following are the key features of the GET by ID operation:
- It returns the resource with the specific ID
- An example of this type of operation is
http://myserver.com/myapi/v1/products/abcd1234(using the path parameters) orhttp://myserver.com/myapi/v1/products?id=abcd1234(using the query parameters)
Whether you should use path parameters or query parameters is entirely up to you, and it is not mandated by the REST conventions. Here, and for the remainder of the book, we will use query parameters, since this is the normal HTTP way of doing things and a bit easier to understand and implement.
POST requests are used in order to create new instances of a given resource. Normally, a conventional REST server will provide documentation about the fields of the resource that you need to specify for the creation to succeed.
PUT is used in order to create or update a resource. It works almost identically to POST, with the exception that if you supply a resource ID with your request, the server will first find that specific resource and then replace each field of that resource with the equivalent field in your request.
For example, consider a situation where your server has a resource of the product type, as follows:
{
name: 'Apple',
price: 50,
id: 'abcd1234'
}Let's suppose that you submit a PUT request with the following form data:
{
id: 'abcd1234'
price: 500000000,
}The same resource will have the following state on the server after the transaction concludes:
{
name: "Apple",
price: 500000000,
id: "abcd1234"
}