BIM308 – Web Server

Programming
4- RESTful Web Service
Overview of REST
REST stands for Representational State Transfer. To understand what it means,
consider a simple web-based social application.
1. A user visits the home page of the application by typing the address in the
browser.
2. The browser submits an HTTP request to the server.
3. The server responds with an HTML document containing some links and forms.
4. The user types her status in a form and submits the form.
5. The browser submits another HTTP request to the server.
6. The server processes the request and responds with another page.
This cycle continues until the user stops browsing. Except for a few exceptions,
most websites and web-based applications follow the same pattern. Let’s see how
this application is related to REST.
Overview of REST
Uniform Resource Identifiers
What the user types into the browser at the start of the previous
interaction is a Uniform Resource Identifier (URI). Another commonly
used name for this is a Uniform Resource Locator (URL). URI is a more
generalized term that you can use to refer to either a location (URL) or
a name.
A URI is an identifier of a resource. In most cases, URIs are opaque for
clients.
Overview of REST
Resources
A resource is anything that can be identified by a URI. In the first step of
the previous flow (1. A user visits the home page of the application by
typing the address in the browser), the URI typed by the user is the
address of a resource that corresponds to a web page. In a typical static
website, every web page is a resource.
In the fourth step, the part of the server that updates the user’s status
is another resource. The HTML form that is used to submit the form
has the address (URI) of this resource encoded as the value of the
action attribute of the form element. (4. The user types her status in a
form and submits the form.)
Overview of REST
Representations
The HTML document that the server returns to the client is a
representation of the resource. A representation is an encapsulation of
the information (state, data, or markup) of the resource, encoded using
a format such as XML, JSON, or HTML.
A resource may have one or more representations. Clients and servers
use media types to denote the type of the representation to the
receiving party (the client or the server). Most websites and
applications typically use HTML format with text/html as the media
type.
 Overview of REST
Uniform Interface
Clients use the Hypertext Transfer Protocol (HTTP) to submit requests to
resources and get responses. In the first step, the client submits a GET request
to fetch an HTML document. In the fourth step, the client submits a POST
request to update the user status.
These two methods are part of HTTP’s uniform interface. Use of a uniform
interface makes the request and responses self-describing and visible. In
addition to these two methods, this interface consists of other methods such
as OPTIONS, HEAD, PUT, DELETE, TRACE, and CONNECT. Of these methods,
except for the CONNECT method, which HTTP 1.1 reserves for tunneling TCP-
based protocols such as TLS, HTTP defines the semantics of each method.
HTTP is a protocol between clients and resources. In this protocol, except when
you define new methods to extend HTTP, the list of methods and their
semantics is fixed. Those semantics are independent of the resources. That is
why HTTP is called a uniform interface.
 Overview of REST
Hypermedia and Application State
Finally, each representation that the client receives from the server
represents the state of the user’s interaction within the application. For
instance, when the user submits the form to receive another page, the
user changes the state of the application from her point of view. When a
user, just browsing a website, the user changes the state of the
application with each click on a link to load another page.
In this example, to change the state of the application, the user relies on
forms and links found in the HTML. HTML is an hypermedia format,
allowing link and form controls to let you flow through the application
and thereby change the state of the application. This way of using
hypermedia of the representation (such as HTML) to denote and manage
the state of the application is called hypermedia as the engine of
application state, or in short form the hypertext constraint.
 Using the Uniform Interface
HTTP is an application-level protocol that defines operations for
transferring representations between clients and servers. In this protocol,
methods such as GET, POST, PUT, and DELETE are operations on
resources. This protocol eliminates the need for you to invent application-
specific operations such as createOrder, getStatus, updateStatus, etc.
How much you can benefit from the HTTP infrastructure largely depends
on how well you can use HTTP as an application-level protocol.
 Using the Uniform InterfaceUsing the Uniform
Interface
HTTP achieves visibility by virtue of the following:
• HTTP interactions are stateless. Any HTTP intermediary can infer the meaning
of any given request and response without correlating them with past or future
requests and responses.
• HTTP uses a uniform interface consisting of OPTIONS, GET, HEAD, POST, PUT,
DELETE, and TRACE methods. Each method in this interface operates on one
and only one resource. The syntax and the meaning of each method do not
change from application to application or from resource to resource. That is
why HTTP is known as a uniform interface.
• HTTP uses a MIME-like envelope format to encode representations. This
format maintains a clear separation between headers and the body. Headers
are visible, and except for the software that is creating the message and the
software that is processing the message, every piece of software in between
can treat the body as completely opaque
 Using the Uniform Interface
For RESTful web services, the key goal must be to maintain visibility to the
extent possible. Keeping visibility is simple. Use each HTTP method such
that it has the same semantics as specified by HTTP, and add appropriate
headers to describe requests and responses.
 How to Implement Safe and Idempotent
Methods on the Server
Safety and idempotency are guarantees that a Safety and idempotency of HTTP
methods
server must provide to clients in its
Method Safe? Idempotent?
implementation for certain methods. This recipe
GET Yes Yes
discusses why these matter and how to
implement safety and idempotency on the HEAD Yes Yes
server. OPTIONS Yes Yes
PUT No Yes
While implementing GET, OPTIONS, and HEAD DELETE No Yes
methods, do not cause any side effects. When a POST No No
client resubmits a GET, HEAD, OPTIONS, PUT, or
DELETE request, ensure that the server provides
the same response except under concurrent
conditions.
 How to Implement Safe and Idempotent
Methods on the Server
Implementing safe methods Safety and idempotency of HTTP
methods
In HTTP, safe methods are not expected to cause Method Safe? Idempotent?
side effects. Clients can send requests with safe GET Yes Yes
methods without worrying about causing HEAD Yes Yes
unintended side effects. To provide this OPTIONS Yes Yes
guarantee, implement safe methods as read-only PUT No Yes
operations. DELETE No Yes
Safety does not mean that the server must POST No No
return the same response every time. It just
means that the client can make a request
knowing that it is not going to change the state
of the resource.
 How to Implement Safe and Idempotent
Methods on the Server
Implementing idempotent methods Safety and idempotency of HTTP
methods
Idempotency guarantees clients that repeating a Method Safe? Idempotent?
request has the same effect as making a request GET Yes Yes
just once. Idempotency matters most in the case HEAD Yes Yes
of network or software failures. Clients can OPTIONS Yes Yes
repeat such requests and expect the same PUT No Yes
outcome. DELETE No Yes
POST No No
For this approach to work, you must implement
all methods except POST to be idempotent. In
programming language terms, idempotent
methods are similar to “setters.”
 When to Use GET
The infrastructure of the Web strongly relies on the idempotent and safe
nature of GET. Clients count on being able to repeat GET requests
without causing side effects. Caches depend on the ability to serve
cached representations without contacting the origin server.
The purpose of GET is to get a representation of a resource
 When to Use POST
POST is either to create new resources or to make various other changes
to resources
Use POST for the following:
• To create a new resource
• To modify one or more resources via a controller resource
• To run queries with large inputs
• To perform any unsafe or nonidempotent operation when no other
HTTP method seems appropriate
 When to Use PUT to Create New Resources
You can use either HTTP POST or HTTP PUT to create new resources
Use PUT to create new resources only when the client can control part of
the URI. For instance, a storage server may allocate a root URI for each
client and let clients create new resources using that root URI as a root
directory on a filesystem. Otherwise, use POST.
When using POST to create new resources, the server decides the URI
for the newly created resource. It can control its URI naming policies
along with any network security-level configurations. You can still let
servers use information in the representation while generating URIs for
new resources.
 When to Use PUT to Create New Resources
When you support PUT to create new resources, clients must be able to
assign URIs for resources. When using this method to create new
resources, take the following into consideration:
• To let clients assign URIs, the server needs to explain to clients how
URIs on the server are organized, what kind of URIs are valid, and what
kind are not.
• You also need to consider any security and filtering rules set up on
servers based on URI patterns and may want to restrict clients to use a
narrow range of URIs while creating new URIs.
 How to Use DELETE for Asynchronous
Deletion
DELETE is to delete a resource
When resource deletion takes a significant amount of time for cleanup
and archival tasks in the backend.
 When and How to Use Controllers to Operate
on Resources
In the case of RESTful web services, controllers can help increase the
separation of concerns between servers and clients, improve network
efficiency, and let servers implement complex operations atomically.
Designate a controller resource for each distinct operation. Let clients
use the HTTP method POST to submit a request to trigger the operation.
A controller is a resource that can atomically make changes to resources.
The need for such a resource may not be apparent from your domain
model, but it can help the server abstract complex business operations
and provide a way for clients to trigger those operations. This in turn
reduces coupling between clients and servers.
 Designing URIs
URI design is just one aspect of implementing RESTful applications. Here
are some conventions to consider when designing URIs.
URIs has several advantages:
• URIs that support convention are usually easy to debug and manage.
• Servers can centralize code to extract data from request URIs.
• You can avoid spending valuable design and implementation time
inventing new conventions and rules for processing URIs.
• Partitioning the server’s URIs across domains, subdomains, and paths
gives you operational flexibility for load distribution, monitoring, routing,
and security.
 Designing URIs
• Use domains and subdomains to logically group or partition resources for localization,
distribution, or to enforce various monitoring or security policies.
• Use the forward-slash separator (/) in the path portion of the URI to indicate a hierarchical
relationship between resources.
• Use the hyphen (-) and underscore (_) characters to improve the readability of names in
long path segments.
• Use the ampersand (&) to separate parameters in the query portion of the URI.
• Avoid including file extensions (such as .php, .aspx, and .jsp) in URIs unless the technology
used needs to change.
Examples:
http://www.example.org/customer/orders/order1
http://www.example.org/blog/this-is-my-first-post
http://www.example.org/my_photos/our_summer_vacation/first_day/setting_up_camp/
http://www.example.org/search?word=Antarctica&limit=30
References
Allamaraju, S. (2010). RESTful web services cookbook: solutions for
improving scalability and simplicity. " O'Reilly Media, Inc.".