Lecture 25: REST

Internet Technologies and Web

Services – CSE2034Y
 REST
• REST stands for Representational State Transfer.
(It is sometimes spelled "ReST".) It relies on a
stateless, client-server, cacheable
communications protocol -- and in virtually all
cases, the HTTP protocol is used.
• RESTful applications use HTTP requests to post
data (create and/or update), read data (e.g.,
make queries), and delete data. Thus, REST uses
HTTP for all four CRUD
(Create/Read/Update/Delete) operations.
 Why use REST?
• REST is a lightweight alternative to
mechanisms like RPC (Remote Procedure
Calls) and Web Services (SOAP, WSDL, et al.)
• Despite being simple, REST is fully-featured;
almost everything you can do in Web Services
can be done using RESTful architecture.
• REST is not a "standard". There will never be a
W3C recommendation for REST, for example
 REST Architecture
• In REST architecture, a REST Server simply
provides access to resources and REST client
accesses and presents the resources.
• Here each resource is identified by URIs/
global IDs.
• REST uses various representations to
represent a resource like text, JSON and XML.
Nowadays JSON is the most popular format
being used in web services.
 Real-life examples of REST
• Here's a very partial list of service providers that use a REST
API. Note that some of them also support a WSDL (Web
Services) API, in addition, so you can pick which to use; but
in most cases, when both alternatives are available, REST
calls are easier to create, the results are easier to parse and
use, and it's also less resource-heavy on your system.
– The Google Glass API, known as "Mirror API", is a pure REST API.
– Twitter has a REST API (in fact, this was their original API ).
– Flickr.
– Amazon.com offer several REST services, e.g., for their S3
storage solution.
– Atom is a RESTful alternative to RSS.
– Tesla Model S uses an (undocumented) REST API between the
car systems and its Android/iOS apps.
 REST Web Services
• Every system uses resources. These resources can be pictures, video files,
Web pages, business information, or anything that can be represented in a
computer-based system. The purpose of a service is to provide a window
to its clients so that they can access these resources. Service architects
and developers want this service to be easy to implement, maintainable,
extensible, and scalable. A RESTful design promises that and more. In
general, RESTful services should have following properties and features:
• Representations
• Messages
• URIs
• Uniform interface
• Stateless
• Links between resources
• Caching
 Representations
• The focus of a RESTful service is on resources and how to provide access to
these resources. A resource can easily be thought of as an object .
• A resource can consist of other resources. While designing a system, the
first thing to do is identify the resources and determine how they are
related to each other. This is similar to the first step of designing a
database: Identify entities and relations.
• Once we have identified our resources, the next thing we need is to find a
way to represent these resources in our system. You can use any format
for representing the resources, as REST does not put a restriction on the
format of a representation.
• For example, depending on your requirement, you can decide to use JSON
or XML. If you are building Web services that will be used by Web pages
for AJAX calls, then JSON is a good choice. XML can be used to represent
more complex resources. For example a resource called "Person" can be
represented as:
JSON Representation of a resource
{
"ID": "1",
"Name": "M Vaqqas",
"Email": "m.vaqqas@gmail.com",
"Country": "India"
}
 XML Representation of a resource
<Person>

<ID>1</ID>

<Name>M Vaqqas</Name>

<Email>m.vaqqas@gmail.com</Email>

<Country>India</Country>
</Person>
 Representations (2)
• We can use more than one format and decide which one to use for
a response depending on the type of client or some request
parameters. A good representation should have some obvious
qualities:
– Both client and server should be able to 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 breaking this resource into child resources. Dividing big
resources 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 capable of linking resources to each
other. This can be done by placing the URI or unique ID of the related
resource in a representation (more on this in the coming sections).
 Messages
• The client and service talk 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 some metadata about the message.
• It is important to have some background about
the HTTP 1.1 request and response formats for
designing RESTful Web services.
 HTTP Request
• <VERB> is one of the HTTP methods like GET, PUT, POST, DELETE,
OPTIONS, etc
• <URI> is the URI of the resource on which the operation is going to
be performed
• <HTTP Version> is the version of HTTP, generally "HTTP v1.1" .
• <Request Header> contains the metadata as a collection of key-
value pairs of headers and their values. These settings contain
information about the message and its sender like client type, the
formats client supports, format type of the message body, cache
settings for the response, and a lot more information.
• <Request Body> is the actual message content. In a RESTful service,
that's where the representations of resources sit in a message.
• There are no tags or markups to denote the beginning or end of a
section in an HTML message.
 A sample POST request
A sample POST request message, which is supposed to insert
a new resource Person.
POST http://MyService/Person/
Host: MyService
Content-Type: text/xml; charset=utf-8
Content-Length: 123
<?xml version="1.0" encoding="utf-8"?>
<Person>
<ID>1</ID>
<Name>M Vaqqas</Name>
<Email>m.vaqqas@gmail.com</Email>
<Country>India</Country>
</Person>
Sample POST request - explanation
• You can see the POST command, which is followed by
the URI and the HTTP version. This request also
contains some request headers.
• Host is the address of the server. Content-Type tells
about the type of contents in the message body.
• Content-Length is the length of the data in message
body. Content-Length can be used to verify that the
entire message body has been received.
• Notice there are no start or end tags in this message.
 A sample GET request
GET request that was created by the browser when
visiting the HTTP 1.1 specifications on w3.org:
GET http://www.w3.org/Protocols/rfc2616/rfc2616.html
HTTP/1.1
Host: www.w3.org
Accept:
text/html,application/xhtml+xml,application/xml; …
User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64)
AppleWebKit/537.36 …
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8,hi;q=0.6
 Sample GET request - explanation
• There is no message body in this request. The
Accept header tells the server about the various
presentation formats this client supports. A
server, if it supports more than one
representation format, it can decide the
representation format for a response at runtime
depending on the value of the Accept header.
User-Agent contains information about the type
of client who made this request. Accept-
Encoding/Language tells about the encoding and
language this client supports.
 HTTP Response
• The server returns <response code>, which contains
the status of the request. This response code is
generally the 3-digit HTTP status code.
• <Response Header> contains the metadata and
settings about the response message.
• <Response Body> contains the representation if the
request was successful.
 A sample response to a GET request
HTTP/1.1 200 OK
Date: Sat, 23 Aug 2014 18:31:04 GMT
Server: Apache/2
Last-Modified: Wed, 01 Sep 2004 13:24:52 GMT
Accept-Ranges: bytes
Content-Length: 32859
Cache-Control: max-age=21600, must-revalidate
Expires: Sun, 24 Aug 2014 00:31:04 GMT
Content-Type: text/html; charset=iso-8859-1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns='http://www.w3.org/1999/xhtml'>
<head><title>Hypertext Transfer Protocol -- HTTP/1.1</title></head>
<body>
...
 Explanations
• The response code 200 OK means that everything
went well and the response message body
contains a valid representation of the resource I
requested.
• In this case, the representation is an HTML
document that is declared by Content-Type
header in the response header.
• The headers in the message are self explanatory.
• There are many other attributes.
• You can catch and inspect such HTTP requests
and responses using a free tool called Fiddler.
 URIs - Adding Resources
• REST requires each resource to have at least one URI.
• A RESTful service uses a directory hierarchy like human readable
URIs to address its resources. The job of a URI is to identify a
resource or a collection of resources. The actual operation is
determined by an HTTP verb. The URI should not say anything
about the operation or action. This enables us to call the same URI
with different HTTP verbs to perform different operations.
• Suppose we have a database of persons and we wish to expose it to
the outer world through a service. A resource person can be
addressed like this:
http://MyService/Persons/1
• This URL has following format:
Protocol://ServiceName/ResourceType/ResourceID
 Query Parameters in URI
• The preceding URI is constructed with the
help of a query parameter:
• http://MyService/Persons?id=1
• The query parameter approach works just fine
and REST does not stop you from using query
parameters.
 Uniform Interface
• RESTful systems should have a uniform interface. HTTP 1.1
provides a set of methods, called verbs, for this purpose.
Among these the more important verbs are:
• GET - Provides a read only access to a resource.
• PUT - Used to create a new resource.
• DELETE - Used to remove a resource.
• POST - Used to update a existing resource or create a new
resource.
• OPTIONS - Used to get the supported operations on a
resource.
• HEAD - Return only the response headers and no response
body.
 Uniform Interface
• GET is probably the most popular method on the Web.
It is used to fetch a resource.
• HEAD returns only the response headers with an empty
body. This method can be used in a scenario when you
do not need the entire representation of the resource.
For example, HEAD can be used to quickly check
whether a resource exists on the server or not.
• The method OPTIONS is used to get a list of allowed
operations on the resource. For example consider the
request:
OPTIONS http://MyService/Persons/1 HTTP/1.1
HOST: MyService
 Uniform Interface (2)
• The service after authorizing and authenticating the
request can return something like:
200 OK
Allow: HEAD, GET, PUT
• The second line contains the list of operations that are
allowed for this client.
• You should use these methods only for the purpose for
which they are intended. For instance, never use GET
to create or delete a resource on the server. If you do,
it will confuse your clients and they may end up
performing unintended operations.
 Stateless
• A RESTful service is stateless and does not
maintain the application state for any client.
• A request cannot be dependent on a past request
and a service treats each request independently.
• HTTP is a stateless protocol by design and you
need to do something extra to implement a
stateful service using HTTP.
• But it is really easy to implement stateful services
with current technologies.
 Stateless/Stateful
• A stateless design looks like so:
Request1: GET http://MyService/Persons/1 HTTP/1.1
Request2: GET http://MyService/Persons/2 HTTP/1.1
• Each of these requests can be treated separately.
• A stateful design, on the other hand, looks like so:
Request1: GET http://MyService/Persons/1 HTTP/1.1
Request2: GET http://MyService/NextPerson HTTP/1.1
• To process the second request, the server needs to
remember the last PersonID that the client fetched. In
other words, the server needs to remember the
current state — otherwise Request2 cannot be
processed.
 Links between Resources
• A resource representation can contain links to other
resources like an HTML page contains links to other pages.
• The representations returned by the service should drive
the process flow as in case of a website.
• When you visit any website, you are presented with an
index page. You click one of 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 coming to a website.
• A service can be (and should be) designed in the same
manner.
 Links between Resources (2)
• Let's consider the case in which a client
requests one resource that contains multiple
other resources.
• Instead of dumping all these resources, you
can list the resources and provide links to
them.
• Links help keep the representations small in
size.
 Example
<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
• Caching is the concept of storing the generated results
and using the stored results instead of generating them
repeatedly if the same request arrives in the near
future.
• This can be done on the client, the server, or on any
other component between them, such as a proxy
server.
• Caching is a great way of enhancing the service
performance, but if not managed properly, it can result
in client being served stale results.
• Caching can be controlled using these HTTP headers:
 Caching (2)
Header Application
Date Date and time when this representation was generated.
Last Modified Date and time when the server last modified 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 since this was fetched from the server. Can
be inserted by an intermediary component.

• Caching can be controlled using the above

HTTP headers.
 Documenting a RESTful Service
• RESTful services do not necessarily require a
document to help clients discover them.
• Due to URIs, links, and a uniform interface, it is
extremely simple to discover RESTful services at
runtime.
• A client can simply know the base address of the
service and from there it can discover the service
on its own by traversing through the resources
using links.
• The method OPTION can be used effectively in
the process of discovering a service.
 Documenting a RESTful Service (2)
• This does not mean that RESTful services require no documentation
at all.
• You should document every resource and URI for client developers.
• You can use any format for structuring your document, but it should
contain enough information about resources, URIs, Available
Methods, and any other information required for accessing your
service.
• The Table below is a sample documentation of MyService. This is a
simple and short document that contains all the aspects of
MyService and should be sufficient for developing a client.
• Service Name: MyService
• Address: http://MyService/
Example of documenting a service
Resource Methods URI Description
Person GET,POST,PU http://MyService/Persons/{Per Contains information about a
T, DELETE sonID} person
{PersonID} is optional
Format: text/xml
Club GET,POST,PU http://MyService/Clubs/{ClubI Contains information about a club.
T D} 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
 Server Structure
• Get the http verb by using
$_SERVER["REQUEST_METHOD“]
• Get the parameters/data from the URL
• Initialise DB connection - Use PDO library to
deal with DB processing
• Create response in appropriate format
XML/JSON
• Send back response.
 Example of server
<?php else{
deliver_response(200,"book found",$price); }
//process client request - request via url }
else
header("Content- {
Type:application/json"); deliver_response(400,"Invalid Request",NULL);
include("functions.php"); }

if(!empty($_GET['name'])){ function
deliver_response($status,$status_message,$data){
$name=$_GET['name']; header("HTTP/1.1 $status $status_message");
$price = get_price($name); $response['status']=$status;
$response['status_message']=$status_message;
$response['data']=$data;
if(empty($price)){ //encode in json format
$json_response=json_encode($response);
deliver_response(200,"book not echo $json_response;
found",NULL); }
?>
}
Results: http://localhost/rest?name=c
 .htaccess.txt
#Turn on the rewrite engine
Options +FollowSymLinks
RewriteEngine On

#Request routing
RewriteRule ^([a-zA-Z_-]*)$ index.php?name=$1
[nc,qsa]
Curl and web services – Steps to create
a client
• Initialise the curl session
– Set the required options
– Specify the service location
– Specify the request method
– Disallow dumping of result on console
– etc
• Send the request
• Close the curl session
 Curl
• CURL wraps the libcurl library which is a multi-
protocol file transfer library.
• This not only allows transmission over http, but
other protocols such as https, ftp, etc.
• Note: You need to enable CURL extension on your
application server. Min php req: php 4.02
• In easyphp, the file php.ini needs to be
configured (binaries/conf_files/) – the extension
should be uncommented
• extension=php_curl.dll –remove the ; in front
 Curl methods
• Setting the right curl options is very important since this will determine the http method used to
send the request. Remember, RESTful URLs do not contain functions name or the http method
name!
• cURL function name Description
• CURLOPT_URL The location of the resource to process
• CURLOPT_{POST|PUT} CURLOPT_POST, CURLOPT_PUT are used for their
respective http methods.
• CURLOPT_CUSTOMREQUEST This is used to implement DELETE http method.
• CURLOPT_POSTFIELDS Specifies the data which is sent in the request body. This
is used in conjunction with CURLOPT_POST,
CURLOPT_PUT mostly
• CURLOPT_RETURNTRANSFER When this option is specified, the response from the
server is not directly printed on console. It can be stored
in a variable for more processing. E.g., apply XSL etc.
• Other options More options are available at:
http://php.net/manual/en/function.curl-setopt.php
Make sure you check them.
 Example of client.php
<html> //send request to the Resource using CURL
<body> //initialise library
<form method="post" action="client.php"> $client = curl_init($url);
Book Name:<input type="text" name="name"/>
<input type="submit" name="submit" value="Get curl_setopt($client,CURLOPT_RETURNTRANSFER,
Price"/> 1);//to save as a variable
</form>
</body> //get response from Resource
</html> $response = curl_exec($client);
<?php //echo $response;
//code to consume a web service in REST //decode
if(isset($_POST['submit'])){ $result = json_decode($response);
$name = $_POST['name']; echo $result->data;
//Resource Address }
$url = "http://localhost/REST/$name";
?>
 References
• http://www.drdobbs.com/
• Previous CSE2034Y lecture notes