RESTful web services

As we have already defined REST and web services, we can now say that a RESTful web service is any web service that is REST-compliant.

Now, as we have already defined RESTful web services, we need to learn how RESTful web services work, and what RESTful web services are based on and why they are preferred over other web services such as SOAP.

Conventions of RESTful web services

RESTful web services are based on RESTful resources. A RESTful resource is an entity/resource that is mostly stored on a server and that client request using RESTful web services. Here are a few characteristics of a resource in terms of RESTful web services:

• It is an entity normally referred as a noun in the URL
• It is unique
• It has data associated with it
• It has at least one URI

If you are still wondering what exactly is a resource, consider the example of a blog. In a blog system, a Post, User, Category, or Comment can be a resource. In a shopping cart, a Product, Category, or an Order can be a resource. In fact, any entity which a client is requesting from the server is a resource.

Most commonly, there are five typical operations which can be performed on a resource:

• List
• Create
• Read
• Update
• Delete

For each operation, we need two things: the URI and HTTP method or verb.

The URI contains a resource name that is a noun and the HTTP method that is a verb. To perform some operation on an entity, we need to have a noun that tells us which entity we need to perform some operation. We also need to specify a verb to tell us what operation we want to perform.

For the preceding mentioned operations, there is a URL convention that we use with HTTP verbs and resource names. In the next section, we will review the URL structure and HTTP verbs for each operation.

HTTP verbs and URL structure

Here is how these operations can be performed on a resource using a combination of URIs and HTTP verbs. Note, in the following mentioned operation's URIs, you need to replace {resource} with a resource name.

List operation

• HTTP method : GET
• URI: /{resource}
• Result: It returns the list of the type of resource whose name is mentioned. In that list, it will give unique identifiers for the resource and these identifiers can be used to perform other operations on that particular resource.

Create operation

• HTTP method : POST
• URI: /{resource}
• Parameters: can be multiple parameters in POST body
• Result: This should create a new resource with parameters in the body.
• As you can see, there is no difference in the URI for Create and List but these two operations are distinguished by the HTTP method which results in different operations. In fact, a combination of the HTTP method and URI tells which operation should be performed.

READ operation

HTTP method: GET

URI: /{resource}/{resource_id}

Result: This should return the record based on the resource's ID.

Here resource_id will be the ID of the resource which can be found from the List operation's result.

Update operation

There can be two types of update operations:

• Update some attributes of a particular record
• Replace that particular record completely with a new one

Only thing that change to perform these two operations: HTTP method.

With the Update operation, to update some of attributes of the resource use:

HTTP method: PATCH

While to replace the whole resource use:

HTTP method: PUT

The URI and the parameters will remain the same:

URI: /{resource}/{resource_id}

Parameters: There can be multiple parameters in a query string. Initially, people try to pass these parameters in the body but actually, the PATCH and PUT parameters are passed using a query string.

Result: This should update or replace the resource based on the HTTP method.

Here, resource_id will be the ID of the resource which can be found from the List operation's result. Again, practically using PATCH or PUT will not make any difference but based on REST standards PATCH should be used for updating the different attributes of a record while PUT should be used for replacing the whole resource.

Delete operation

• HTTP method: DELETE
• URI: /{resource}/{resource_id}
• Result: This should delete the resource based on the resource ID in the URI

If you feel overwhelmed at the moment, don't worry, because right now we have just seen which combination of HTTP method and URI is used for which operations. Shortly, we will discuss a case study and will see some operations on different resources along with examples.

Before anything else, since we now know about RESTful web services and how they work, it's a good time to understand why we prefer to use RESTful web services over other web services.