What are RESTful Web Services?

Web vs Web Service
What is RESTful Service?
Use HTTP methods explicitly
Be stateless
Expose directory structure-like URIs
Transfer XML, JSON, or both
Java RESTful Service for Beginners

1. Web vs Web Service

Before answering the question of RESTful, I want you to recognize the difference between web and web service.

When you enter a URL in the browser and you will get a website. This is a content that you can read and its content is for the end users.

Web Service is a broader concept than the concept of regular web, it provides the raw information, and confusing to most users, So it is used by applications. These applications will analyse the raw data before returning it to the end users.

For example, when you enter a certain ABC website to see the weather information and securities information. The website will display the information you want.

In order to get the data of weather, the ABC application need to get the information from a certain source. The source can be a web service that provides the weather data to each region respectively.

Similarly, in order to get the securities data, ABC application need to contact with the supply services of the data. The data will be processed before returning a complete website to you.

Web Services often supply the raw data that is difficult to understand for most of the common end users and the Web Services are often returned in the XML or JSON format.

2. What is RESTful Service?

RESTful Web Service is a Web Service that uses the REST structure. REST has been widely used, replacing Web services based on SOAP and WSDL. RESTful Web services are lightweight, easy to extend and maintain.

The first concept of REST (Representational State Transfer) was given out in the doctoral dissertation Roy Thomas Fielding in 2000 (The co-founder of the HTTP protocol). His research details the constrains, the rules and the way to perform in the system in order to get a REST system.

REST defines a set of architectural principles by which you can design Web services that focus on a system's resources, including how resource states are addressed and transferred over HTTP by a wide range of clients written in different languages. If measured by the number of Web services that use it, REST has emerged in the last few years alone as a predominant Web service design model. In fact, REST has had such a large impact on the Web that it has mostly displaced SOAP- and WSDL-based interface design because it's a considerably simpler style to use.

REST is a set of rules that aims at creating a Web Service application according to four basic rules below:

Use HTTP methods explicitly.
Be stateless.
Expose directory structure-like URIs.
Transfer XML, JavaScript Object Notation (JSON), or both.

-

3. Use HTTP methods explicitly

REST gives out a rule requiring programmers to specify their purpose via the method of HTTP. The purposes normally include getting, inserting, updating or deleting the data. In case you want to perform one of the purposes, you need to make a note of the rules below:

To create a resource on the server, use POST.
To retrieve a resource, use GET.
To change the state of a resource or to update it, use PUT.
To remove or delete a resource, use DELETE.

Note that the rules above are not mandatory, in fact you can use the mode of GET to obtain the data, to insert, edit or delete the data on Server. However REST gives out the above-mentioned rules that aims to make all clearer and more understandable.

The example below is the way that you use GET to add more the data on server (Note that here is contrary to the rules of REST).

Use GET to require to adding a user named as Robert.

GET /adduser?name=Robert HTTP/1.1

Use GET to require the server to rename the name of users from Robert to Smith.

GET /updateuser?name=Robert&amp;newname=Smith HTTP/1.1

And all of things now become clearer according to the rules of REST.

Send HTTP POST request to add data:

POST /users/Robert HTTP/1.1
Host: myserver
Content-Type: application/xml
<?xml version="1.0"?>
<user>
<name>Robert</name>
</user>

Let's send a GET request if you want to get the data on the system.

GET /users/Robert HTTP/1.1
Host: myserver
Accept: application/xml

Let's send a PUT request if you want to update the data.

PUT /users/Robert HTTP/1.1
Host: myserver
Content-Type: application/xml
<?xml version="1.0"?>
<user>
 <name>Smith</name>
</user>

Let's send a DELETE request if you want to delete the data.

DELETE /users/Robert HTTP/1.1

4. Be stateless

One feature of REST is stateless that means it does not store information of the client. For example, you just send a request to see the page 2 of a document, and you now want to see the next page (Page 3). REST will not store the information that serving you the page 2 previously. It means that REST does not manage Session.

The image below illustrates a state storage application that knows which page number the users are viewing. And the users only requires "Next page" to see the desired page.

For stateless designs, Client must send out a clear requirement including page number

Stateless server-side components, on the other hand, are less complicated to design, write, and distribute across load-balanced servers. A stateless service not only performs better, it shifts most of the responsibility of maintaining state to the client application. In a RESTful Web service, the server is responsible for generating responses and for providing an interface that enables the client to maintain application state on its own.

5. Expose directory structure-like URIs

REST gives out a struture that users can access to its resources via URLs. The resources here is all of things that you can name (Video, image, weather report,...)

You need to create the REST services that return resources to users respectively.

REST Web service URIs should be intuitive to the point where they are easy to guess. Think of a URI as a kind of self-documenting interface that requires little, if any, explanation or reference for a developer to understand what it points to and to derive related resources. To this end, the structure of a URI should be straightforward, predictable, and easily understood.

The URL below provides the weather information of a location for a specific day, and it is understandable to users.

http://myservice.com/weather/chicago/2016-09-27

http://myservice.com/weather/hanoi/2016-11-11

Some additional guidelines to make note of while thinking about URI structure for a RESTful Web service are:

Hide the server-side scripting technology file extensions (.jsp, .php, .asp), if any, so you can port to something else without changing the URIs.
Keep everything lowercase.
Substitute spaces with hyphens or underscores (one or the other).
Avoid query strings as much as you can.
Instead of using the 404 Not Found code if the request URI is for a partial path, always provide a default page or resource as a response.

6. Transfer XML, JSON, or both

When the Client sends a request to the web service, it is often transmitted in XML or JSON and often gets similar forms back.

The Client can occasionally specify the return data type that it wants (JSON, or XML,..), the designations is called as the MINE types enclosing on the HEADER of request.

Below is the common MINE types using with REST service.

JSON	application/json
XML	application/xml
XHTML	application/xhtml+xml

For example, the client sends a request to get weather information and requires the return data in the XML format.

GET /weather/chicago/2016-08-27 HTTP/1.1
Host: myservice.com
Accept: application/xml;q=0.5

And data received:

<weather>
    <date>2016-08-27</date>
    <location>Chicago</location>
    <info>Hot</info>"//
</weather>

In case the client requires the return data in the JSON format:

{
 "date": "2016-08-27",
 "location": "Chicago",
 "info": "Hot"
}