RESTful Web Services
Introduction
RESTful Web Services are basically REST Architecture based Web Services. In REST Architecture everything
is a resource. RESTful web services are light weight, highly scalable and maintainable and are very
commonly used to create APIs for web-based applications. Restful Web Service, expose API from your
application in a secure, uniform, stateless manner to the calling client. The calling client can perform
predefined operations using the Restful service. The underlying protocol for REST is HTTP. REST stands for
REpresentational State Transfer.
What is REST architecture?
REST stands for REpresentational State Transfer. REST is web standards based architecture and uses HTTP
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 was first introduced by Roy Fielding in 2000.
In REST architecture, a REST Server simply provides access to resources and REST client accesses and
modifies the resources. Here each resource is identified by URIs/ global IDs. REST uses various
representation to represent a resource like text, JSON, XML. JSON is the most popular one.
HTTP methods
Following four HTTP methods are commonly used in REST based architecture.
GET − Provides a read only access to a resource.
POST − Used to create a new resource.
DELETE − Used to remove a resource.
PUT − Used to update a existing resource or create a new resource.
Introduction to RESTFul web services
A web service is a collection of open protocols and standards used for exchanging data between
applications or systems. Software applications written in various programming languages and running on
various platforms can use web services to exchange data over computer networks like the Internet in a
manner similar to inter-process communication on a single computer. This interoperability (e.g., between
Java and Python, or Windows and Linux applications) is due to the use of open standards.
Web services based on REST Architecture are known as RESTful web services. These webservices uses
HTTP methods to implement the concept of REST architecture. A RESTful web service usually defines a
URI, Uniform Resource Identifier a service, provides resource representation such as JSON and set of HTTP
Methods.
RESTful Resources
What is a Resource?
REST architecture treats every content as a resource. These resources can be Text Files, Html Pages,
Images, Videos or Dynamic Business Data. REST Server simply provides access to resources and REST client
accesses and modifies the resources. Here each resource is identified by URIs/ Global IDs. REST uses
various representations to represent a resource where Text, JSON, XML. The most popular
representations of resources are XML and JSON.
Representation of Resources
A resource in REST is a similar Object in Object Oriented Programming or is like an Entity in a Database.
Once a resource is identified then its representation is to be decided using a standard format so that the
server can send the resource in the above said format and client can understand the same format.
For Example : a user is a resource which is represented using the following XML format −
<user>
<id>1</id>
<name>Mahesh</name>
<profession>Teacher</profession>
</user>
The same resource can be represented in JSON format as follows −
{
"id":1,
"name":"Mahesh",
"profession":"Teacher"
}
Good Resources Representation
REST does not impose any restriction on the format of a resource representation. A client can ask for JSON
representation whereas another client may ask for XML representation of the same resource to the server
and so on. It is the responsibility of the REST server to pass the client the resource in the format that the
client understands.
Following are some important points to be considered while designing a representation format of a
resource in RESTful Web Services.
Understandability − Both the Server and the Client should be able to understand and utilize the
representation format of the resource.
Completeness − Format should be able to represent a resource completely. For example, a
resource can contain another resource. Format should be able to represent simple as well as
complex structures of resources.
Linkability − A resource can have a linkage to another resource, a format should be able to handle
such situations.
However, at present most of the web services are representing resources using either XML or JSON
format. There are plenty of libraries and tools available to understand, parse, and modify XML and JSON
data.
RESTful Messages
RESTful Web Services make use of HTTP protocols as a medium of communication between client and
server. A client sends a message in form of a HTTP Request and the server responds in the form of an
HTTP Response. This technique is termed as Messaging. These messages contain message data and
metadata i.e. information about message itself. Let us have a look on the HTTP Request and HTTP
Response messages for HTTP 1.1.
HTTP Request
An HTTP Request has five major parts −
Verb − Indicates the HTTP methods such as GET, POST, DELETE, PUT, etc.
URI − Uniform Resource Identifier (URI) to identify the resource on the server.
HTTP Version − Indicates the HTTP version. For example, HTTP v1.1.
Request Header − Contains metadata for the HTTP Request message as key-value pairs. For
example, client (or browser) type, format supported by the client, format of the message body,
cache settings, etc.
Request Body − Message content or Resource representation.
HTTP Response
An HTTP Response has four major parts −
Status/Response Code − Indicates the Server status for the requested resource. For example, 404
means resource not found and 200 means response is ok.
HTTP Version − Indicates the HTTP version. For example HTTP v1.1.
Response Header − Contains metadata for the HTTP Response message as keyvalue pairs. For
example, content length, content type, response date, server type, etc.
Response Body − Response message content or Resource representation.
RESTful Addressing
Addressing refers to locating a resource or multiple resources lying on the server. It is analogous to locate
a postal address of a person.
Each resource in REST architecture is identified by its URI (Uniform Resource Identifier). A URI is of the
following format −
<protocol>://<service-name>/<ResourceType>/<ResourceID>
Purpose of an URI is to locate a resource(s) on the server hosting the web service. Another important
attribute of a request is VERB which identifies the operation to be performed on the resource.
For Example : http://localhost:8080/UserManagement/rest/UserService/users and the VERB is GET
Constructing a Standard URI
The following are important points to be considered while designing a URI −
Use Plural Noun − Use plural noun to define resources. For example, we've used users to identify
users as a resource.
Avoid using spaces − Use underscore (_) or hyphen (-) when using a long resource name. For
example, use authorized_users instead of authorized%20users.
Use lowercase letters − Although URI is case-insensitive, it is a good practice to keep the url in
lower case letters only.
Maintain Backward Compatibility − As Web Service is a public service, a URI once made public
should always be available. In case, URI gets updated, redirect the older URI to a new URI using the
HTTP Status code, 300.
Use HTTP Verb − Always use HTTP Verb like GET, PUT and DELETE to do the operations on the
resource. It is not good to use operations name in the URI.
Example
Following is an example of a poor URI to fetch a user.
http://localhost:8080/UserManagement/rest/UserService/getUser/1
Following is an example of a good URI to fetch a user.
http://localhost:8080/UserManagement/rest/UserService/users/1
RESTful Methods
As we have discussed so far that RESTful web service makes heavy uses of HTTP verbs to determine the
operation to be carried out on the specified resource(s). Following table states the examples of common
use of HTTP Verbs.
HTTP Method GET
URI http://localhost:8080/UserManagement/rest/UserService/users
Operation Get list of users
Operation Type Read Only
HTTP Method GET
URI http://localhost:8080/UserManagement/rest/UserService/users/1
Operation Get user of Id 1
Operation Type Read Only
HTTP Method POST
URI http://localhost:8080/UserManagement/rest/UserService/users/2
Operation Insert user with Id 2
Operation Type Non-Idempotent
HTTP Method PUT
URI http://localhost:8080/UserManagement/rest/UserService/users/2
Operation Update User with Id 2
Operation Type N/A
HTTP Method DELETE
URI http://localhost:8080/UserManagement/rest/UserService/users/1
Operation Delete User with Id 1
Operation Type Idempotent
HTTP Method OPTIONS
URI http://localhost:8080/UserManagement/rest/UserService/users
Operation List the supported operations in web service
Operation Type Read Only
HTTP Method HEAD
URI http://localhost:8080/UserManagement/rest/UserService/users
Operation Returns only HTTP Header, no Body
Operation Type Read Only
Here are important points to be considered:
GET operations are read only and are safe.
PUT and DELETE operations are idempotent means their result will always be same no matter how
many times these operations are invoked.
PUT and POST operation are nearly same with the difference lying only in the result where PUT
operation is idempotent and POST operation can cause different result.
