Learning RESTFUL Web Services

What is Restful Web Service?

REST stands for REpresentational State Transfer

This is used to build Web services that are lightweight, maintainable, and scalable in nature.
A service which is built on the REST architecture is called a RESTful service. The underlying protocol for REST is HTTP, which is the basic web protocol. 
It revolves around resource where every component is a resource and a resource is accessed by a common interface using HTTP standard methods.


REST is a way to access resources which are contained in a particular environment. For example, you could have a server that could be hosting important documents or images or videos. All of these are sort of resources. If a client, say a web browser needs any of these resources, it should request from the server to access these resources. Now REST defines a way on how these resources can be accessed.

The key points of a RESTful implementation are as follows:

Resources 
The first key element is the resource itself. Let assume that a web application on a server has records of several employees. Let's assume the URL of the web application is http://sample.tech.com. Now in order to access an employee record resource via REST, one can issue the command http://sample.tech.com/employee/1 - This command tells the web server to please provide the details of the employee whose employee number is 1.

Request Verbs 
These describe what you want to do with the resource. A browser issues a GET verb to instruct the endpoint it wants to get data. However, there are many other verbs available including things like POST, PUT, and DELETE. So in the case of the example http://sample.tech.com/employee/1, the web browser is actually issuing a GET Verb because it wants to get the details of the employee record.

Request Headers 
These are additional instructions sent with the request. These might define the type of response required or the authorization details.

Request Body 
Data is sent with the request. Data is normally sent in the request when a POST request is made to the REST web service. In a POST call, the client actually tells the web service that it wants to add a resource to the server. Hence, the request body would have the details of the resource which is required to be added to the server.

Response Body 
This is the main body of the response. So in our example, if we were to query the web server via the request http://sample.tech.com/employee/1, the web server might return an XML document with all the details of the employee in the Response Body.

Response Status codes
These codes are the general codes which are returned along with the response from the web server. An example is the code 200 which is normally returned if there is no error when returning a response to the client.

Restful Methods
The below diagram shows mostly all the verbs (POST, GET, PUT, and DELETE) and an example of what they would mean.

Let's assume that we have a RESTful web service is defined at the location. http://sample.tech.com/employee. When the client makes any request to this web service, it can specify any of the normal HTTP verbs of GET, POST, DELETE and PUT. Below is what would happen If the respective verbs were sent by the client.

POST – This would be used to create a new employee using the RESTful web service
GET - This would be used to get a list of all employee using the RESTful web service
PUT - This would be used to update all employee using the RESTful web service
DELETE - This would be used to delete all employee using the RESTful web service


Restful Architecture

RESTful or REST-style has the following characteristics

• State and functionality are divided into distributed resources – This means that every resource should be accessible via the normal HTTP commands of GET, POST, PUT, or DELETE. So if someone wanted to get a file from a server, they should be able to issue the GET request and get the file. If they want to put a file on the server, they should be able to either issue the POST or PUT request. And finally, if they wanted to delete a file from the server, they can issue the DELETE request.

• The architecture is client/server, stateless, layered, and supports caching –Client-server is the typical architecture where the server can be the web server hosting the application, and the client can be as simple as the web browser. Stateless means that the state of the application is not maintained in REST. For example, if you delete a resource from a server using the DELETE command, you cannot expect that delete information to be passed to the next request.

In order to ensure that the resource is deleted, you would need to issue the GET request. The GET request would be used to first get all the resources on the server. After which one would need to see if the resource was actually deleted.

RESTFul Principles and Constraints

Any RESTful web service has to comply with the below characteristics in order for it to be called RESTful. These characteristics are also known as design principles which need to be followed when working with RESTful based services.

RESTFul Client-Server

This is the most fundamental requirement of a REST-based architecture. It means that the server will have a RESTful web service which would provide the required functionality to the client. The client send's a request to the web service on the server. The server would either reject the request or comply and provide an adequate response to the client.

Stateless

The concept of stateless means that it's up to the client to ensure that all the required information is provided to the server. This is required so that the server can process the response appropriately. The server should not maintain any sort of information between requests from the client. It's a very simple independent question-answer sequence. The client asks a question, the server answers it appropriately. The client will ask another question. The server will not remember the previous question-answer scenario and will need to answer the new question independently.

Cache

The Cache concept is to help with the problem of stateless which was described in the last point. Since each server client request is independent in nature, sometimes the client might ask the server for the same request again. This is even though it had already asked for it in the past. This request will go to the server, and the server will give a response. This increases the traffic across the network. The cache is a concept implemented on the client to store requests which have already been sent to the server. So if the same request is given by the client, instead of going to the server, it would go to the cache and get the required information. This saves the amount of to and fro network traffic from the client to the server.

Layered System

The concept of a layered system is that an additional layer such as a middleware layer can be inserted between the client and the actual server hosting the RESTFul web service (The middleware layer is where all the business logic is created. This can be an extra service created with which the client could interact with before it makes a call to the web service.). But the introduction of this layer needs to be transparent so that it does not disturb the interaction between the client and the server.

Interface/Uniform Contract

This is the underlying technique of how RESTful web services should work. RESTful basically works on the HTTP web layer and uses the below key verbs to work with resources on the server

POST - To create a resource on the server

GET - To retrieve a resource from the server

PUT - To change the state of a resource or to update it

DELETE - To remove or delete a resource from the server

Spring Boot - Building RESTful Web Services

Spring Boot provides very good support to building RESTful Web Services for enterprise applications. 

You should add Spring Boot Starter Web dependency into the build configuration file before starting developing.
As Maven dependency:

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-web</artifactId>    
</dependency>

Important Annotations

Rest Controller
The @RestController annotation is used to define RESTful web services. It serves JSON, XML and custom response.

@RestController
public class ProductServiceController { }



Request Mapping
The @RequestMapping annotation is used to define the Request URI to access the REST Endpoints. We can define the Request method to consume and produce an object. The default request method is GET.

@RequestMapping(value = "/products")
public ResponseEntity<Object> getProducts() { }


Request Body
The @RequestBody annotation is used to define the request body content type.

public ResponseEntity<Object> createProduct(@RequestBody Product product) { }

Path Variable
The @PathVariable annotation is used to define the custom or dynamic request URI. The Path variable in request URI is defined as curly braces { } as shown below 

public ResponseEntity<Object> updateProduct(@PathVariable("id") String id) { }

Request Parameter
The @RequestParam annotation is used to read the request parameters from the Request URL. By default, it is a required parameter. We can also set a default value for request parameters as shown here −

public ResponseEntity<Object> getProduct(
   @RequestParam(value = "name", required = false, defaultValue = "honey") String name) { }