1. REST

2. Contents
REST.............................................................................................................................................................................................1
Introduction..........................................................................................................................................................................3
Goals of REST........................................................................................................................................................................4
Features of a RESTful Services...........................................................................................................................................5
Representations ..............................................................................................................................................................5
Messages ..........................................................................................................................................................................5
URIs....................................................................................................................................................................................5
Uniform interface............................................................................................................................................................5
Stateless............................................................................................................................................................................5
Links between resources ...............................................................................................................................................5
Caching..............................................................................................................................................................................6
Advantages of REST.............................................................................................................................................................7
Documenting a RESTful Service.........................................................................................................................................8
References.............................................................................................................................................................................9

3. Introduction
REST stands for Representational State Transfer,which is an architectural stylefor networked hypermedia
applications;itis primarily used to build Web services that are lightweight, maintainable,and scalable.A
servicebased on REST is called a RESTful service.REST is not dependent on any protocol,but almostevery
RESTful serviceuses HTTP as its underlyingprotocol.
The Restful serviceprovides a window to its clients to access the resources.These resources can be pictures,
video files,Web pages, business information,or anythingthat can be represented in a computer-based
system. The serviceis easy to implement, maintain,extend and scale.

4. Goalsof REST
 Scalability of component interactions.
 Generality of interfaces,
 Independent deployment of components,
 Intermediary components to reduce interaction latency,enforce security,and encapsulatelegacy
systems.
REST achieves these goals by applyingthe followingconstraints:
 Resource is unitof identification.
 Resource is manipulated through exchange of representations.
 Resource-generic interaction semantics.
 Self-descriptivemessaging.
 Hypermedia is engine of application state.

5. Featuresof a RESTful Services
In general, RESTful services should havefollowingproperties and features:
Representations
Resource (Objects) can be represented in JSON or XML. A good representation should have some obvious
qualities:
 Both clientand server should be ableto comprehend this format of representation.
 A representation should be able to completely represent a resource. If there is a need to partially
represent a resource, then you should think about breakingthis resource into child resources.
Dividingbigresources into smaller ones also allows you to transfer a smaller representation.Smaller
representations mean less time required to create and transfer them, which means faster services.
 The representation should be capableof linkingresources to each other. This can be done by placing
the URI or unique ID of the related resource in a representation
Messages
The clientand servicetalk to each other via messages. Clients send a request to the server, and the server
replies with a response. Apart from the actual data,these messages also contain somemetadata aboutthe
message.
URIs
Uniform Resource Identifier - This is a uniqueway of identifyingresources on the network. Every resourceon
the web is given a unique identifier - a universal identifier (example,URL). All web browsers,servers,
applicationsunderstand this identifier, which makes iteasy to connect and exchange information between one
another without any issues.
Uniform interface
RESTful systems should havea uniforminterface. Among these the more important verbs are:
Method Operation performed on server Quality
GET Read a resource. Safe
PUT Inserta new resourceor update if the resourcealready
exists.
Idempotent
POST Inserta new resource. Also can be used to update an
existingresource.
N/A
DELETE Delete a resource . Idempotent
OPTIONS Listthe allowed operations on a resource. Safe
HEAD Return only the response headers and no responsebody. Safe
A Safe operation is an operation that does not have any effect on the original valueof the resource.
Stateless
A RESTful serviceis stateless and does not maintain the application statefor any client. A request cannot be
dependent on a pastrequest and a servicetreats each request independently. HTTP is a stateless protocol by
design and you need to do something extra to implement a stateful serviceusingHTTP. Stateless services are
easier to host, easy to maintain,and more scalable.Plus,such services can providebetter responsetime to
requests, as itis much easier to load balancethem.
Links between resources
A resourcerepresentation can contain links to other resources likean HTML page contains linksto other
pages. The representations returned by the serviceshould drivethe process flowas in caseof a website. When
you visitany website, you are presented with an index page. You click oneof the links and move to another
page and so on. Here, the representation is in the HTML documents and the user is driven through the website
by these HTML documents themselves. The user does not need a map before comingto a website. A service
can be (and should be) designed in the same manner.

6. Let's consider the casein which a clientrequests one resource that contains multipleother resources.Instead
of dumping all these resources,you can listthe resources and providelinks to them. Links help keep the
representations small in size.
For an example, if multiplePersons can be part of a Club, then a Club can be represented in MyService as in
ListingSix (A Club with links to Persons):
<Club>
<Name>Authors Club</Name>
<Persons>
<Person>
<Name>M. Vaqqas</Name>
<URI>http://MyService/Persons/1</URI>
</Person>
<Person>
<Name>S. Allamaraju</Name>
<URI>http://MyService/Persons/12</URI>
</Person>
</Persons>
</Club>
Caching
Cachingcan be done on client,server or proxy server. Cachingcan be controlled usingthese HTTP headers:
Header Application
Date Date and time when this representation was generated.
Last
Modified
Date and time when the server lastmodified this representation.
Cache-
Control
The HTTP 1.1 header used to control caching.
Expires Expiration date and time for this representation. To support HTTP 1.0
clients.
Age Duration passed in seconds sincethis was fetched from the server.
Can be inserted by an intermediary component.
Values of these headers can be used in combination with the directives in a Cache-Control header to check if
the cached results arestill valid or not.The most common directives for Cache-Control header are:
Directive Application
Public The default. Indicates any component can cachethis
representation.
Private Intermediary components cannot cachethis representation,
only clientor server can do so.
no-cache/no-
store
Cachingturned off.
max-age Duration in seconds after the date-time marked in the Date
header for which this representation is valid.
s-maxage Similar to max-age but only meant for the intermediary caching.
must-
revalidate
Indicates thatthe representation must be revalidated by the
server if max-age has passed.
proxy-validate Similar to max-validatebut only meant for the intermediary
caching.

7. Advantages of REST
 It uses well documented, well established,well used technology and methodology.
 Resource centric rather than method centric.
 Given a URI anyone already knows how to access it.
 It's not another protocol on top of another protocol on top of another protocol on top of...
 The response payload can beof any format (some may call this a disadvantage,however the Web
copes with it, it's justa caseof definingthe application grammar).
 Uses the inherent HTTP security model, certain methods to certain URIs can easily berestricted by
firewall configuration,unlikeother XML over HTTP messagingformats.
 REST makes sense, use what we already have; itis the next logical extension of the web.

8. Documentinga RESTful Service
RESTful services do not necessarily requirea document to help clients discover them. Due to URIs, links,and a
uniform interface,it is extremely simpleto discover RESTful services atruntime. A clientcan simply know the
baseaddress of the serviceand from there itcan discover the serviceon its own by traversingthrough the
resources usinglinks. Themethod OPTION can be used effectively in the process of discoveringa service.
This does not mean that RESTful services requireno documentation at all.There is no excuse for not
documenting your service.You should document every resource and URI for clientdevelopers. You can use
any format for structuringyour document, but it should contain enough information aboutresources,URIs,
AvailableMethods,and any other information required for accessingyour service.The Table below is a sample
documentation of MyService. This is a simpleand shortdocument that contains all theaspects
of MyService and should be sufficientfor developing a client.
Service Name: MyService
Address: http://MyService/
Resource Methods URI Description
Person GET,POST,PUT,
DELETE
http://MyService/Persons/{PersonID} Contains information abouta person
{PersonID}is optional
Format: text/xml
Club GET,POST,PUT http://MyService/Clubs/{ClubID} Contains information abouta club.A
club can be joined my multiple
people
{ClubID}is optional
Format: text/xml
Search GET http://MyService/Search? Search a person or a club
Format: text/xml
Query Parameters:
Name: String, Name of a person or a
club
Country: String, optional,Name of
the country of a person or a club
Type: String, optional,Person or Club.
If not provided then search will result
in both Person and Cubs

9. References
1. http://www.drdobbs.com/article/print?articleId=240169069&siteSectionName=web-development
2. http://msdn.microsoft.com/en-us/magazine/jj883957.aspx
3. http://blog.pivotal.io/pivotal/case-studies-2/tech-start-up-lessons-micro-services-architecture-with-
net-and-rabbitmq
4. http://apievangelist.com/2014/04/15/what-are-some-good-examples-of-hypermedia-apis/

10. Hypermedia: it is a computer-based information retrieval systemthat enables a user to gain or provide access
to texts, audio,videos, photos related to a particular subject.The information is gathered in a non-linear
fashion i.e.user can read all information or can skip certain information.
Hypermedia Applications:An application which uses associativerelationshipsamongstinformation contained
within multiplemedia data for the purpose of facilitatingaccess to,and manipulation of,the information
encapsulated by the data.The purpose of hypermedia is to provide access to and manipulation of information.