RESTful APIs

APIs for a Changing World
RESTful WebAPIs

• Stands for Representational State Transfer.
• The term ‘REST’ was coined by Roy Fielding.
• REST is an architecture style for designing networked applications.
• Consists of a set of constraints that need to be strictly followed in
order to proclaim an application as RESTful.
• The World Wide Web that we all use on a daily basis is a perfect, most
successful example of a RESTful application.
• Designing and building RESTful APIs involves applying the same Web
principles while building APIs for two systems to communicate with
each other without human intervention.
REST Basics

• HTTP stands for Hypertext Transfer Protocol. It is a transport protocol used to transfer
information back and forth.
• REST does not mandate the use of HTTP. Similarly, APIs that use HTTP don’t necessarily
have to follow REST.
• However, HTTP and REST are like Coffee and Donut, or like Pizza and Soda. It’s a wide
practice to use HTTP as the protocol for REST APIs. We’ll follow the same through out this
presentation.
• In fact, the same person who coined the term ‘REST’ was also the co-author of HTTP 1.1
specification. So, the odds are pretty good that he was envisioning REST and HTTP to go
hand in hand even though he claims not.
• APIs that use HTTP are called Web APIs. Web APIs that follow REST style are called RESTful
Web APIs.
HTTP and REST

• REST style SHOULD NOT be used in an application if the main goals
are efficiency and performance. RESTful applications are not efficient
and so, may not perform as highly as expected.
• REST style SHOULD BE used if the main goal is to obtain long-term life
of an application. RESTful applications are durable. This durability is
obtained by ensuring that changes can happen to an application
without breaking things. Just like a normal website. Of course, this is
obtained by sacrificing efficiency and performance.
When to use REST and when not to

• Entering the URL in a browser makes the browser send an HTTP
request to a web server, specifically to the URL.
• One web server may host several URLs, and each URL grants access to
a different bit of the data on the server.
• URL points to something – a product, a user, the home page. The
general technical term for the thing is Resource.
• When a browser sends an HTTP request for a resource, the server
sends a document in response. This document is called a
Representation of the resource.
• In short, URL identifies a resource. When a client makes an HTTP
request to a URL, it gets a representation of the resource. The client
never sees a resource directly. This is a key underlining point to
understand REST.
• URL – identifies one and only one resource. If a website has two
conceptually different things on it, it is expected that the site treat
them as two resources with two different URLs.

HTTP/1.1 200 OK
Content-type: text/html
<!DOCTYPE html>
<html>
<head>
<title>Home</title>
</head>
<body>
<div>
<h1>You type it, we post it!</h1>
<p>Exciting! Amazing!</p>
<p class="links">
<a href="/messages">Get started</a>
<a href="/about">About this site</a>
</p>
</div>
</body>
</html>
GET / HTTP/1.1
Host: www.youtypeitwepostit.com Request
Response

HTTP/1.1 200 OK
<!DOCTYPE html>
<html>
<head>
<title>Messages</title>
</head>
<body>
<div>
<h1>Messages</h1>
<p>
Enter your message below:
</p>
<form action="http://youtypeitwepostit.com/messages"
method="post">
<input type="text" name="message" value="" required="true"
maxlength="6"/>
…
GET /messages HTTP/1.1
Response

HTTP/1.1 303 See Other
Location:
http://www.youtypeitwepostit.com/messages/5266722824890167
POST /messages HTTP/1.1
Host: www.youtypeitwepostit.com
Content-type: application/x-www-form-urlencoded
message=Hello!&submit=Post
Request
Response
HTTP/1.1 200 OK
GET /messages/5266722824890167 HTTP/1.1
Response
<!DOCTYPE html>
<html>
…

Application State
Resource State

Connectedness (HATEOAS) in the Web

• Interface Constraints
• Architectural Constraints
REST Constraints … just like the web

Identification of Resources
• Traditional hypertext systems… use unique node or document
identifiers that change every time the information changes, relying
on link servers to maintain references separately from the content.
Since centralized link servers are an anathema to the immense scale
and multi-organizational domain requirements of the Web, REST
relies instead on the author choosing a resource identifier that best
fits the nature of the concept being identified.
REST Interface Constraints

Manipulation of Resources Through Representations
• REST components perform actions on a resource by using a
representation to capture the current or intended state of that
resource and transferring that representation between components.
A representation is a sequence of bytes, plus representation
metadata to describe those bytes.

Self-Descriptive Messages
• REST enables intermediate processing by constraining messages to be
self-descriptive:
interaction is stateless between requests, standard methods and media types are
used to indicate semantics and exchange information, and responses explicitly
indicate cacheability.

The Hypermedia Constraint: Hypermedia As The Engine of Application State
(HATEOAS)
• All application state is kept on the client side. Changes to application state are
the client’s responsibility.
• The client can only change its application state by making an HTTP request and
processing the response.
• How does the client know which requests it can make next? By looking at the
hypermedia controls in the representations it’s received so far.
• Therefore, hypermedia controls are the driving force behind changes in
application state.

Client-Server
• A client component, desiring that a service be performed, sends a
request to the server via a connector. The server either rejects or
performs the request and sends a response back to the client.
Statelessness (No Sessions on server-side)
• The goal is to improve server scalability by eliminating any need for the
server to maintain an awareness of the client state beyond the current
request.
REST Architectural Constraints

Caching
• Thanks to the statelessness constraint, an HTTP request can be considered on
its own, independent of any other requests. These two constraints make
caching possible.
Uniform Interface
• Implementations are decoupled from the services they provide, which
encourages independent evolvability. The trade-off, though, is that a uniform
interface degrades efficiency, since information is transferred in a standardized
form rather than one which is specific to an application’s needs.

Layered System
• Layered-client-server adds proxy and gateway components to the client-server
style. These additional mediator components can be added in multiple layers
to add features like load balancing and security checking to the system.
Code On Demand (The Only Optional Constraint)
• A client component has access to a set of resources, but not the know-how on
how to process them. It sends a request to a remote server for the code
representing that knowhow, receives that code, and executes it locally. The
most significant limitation is the lack of visibility due to the server sending
code instead of simple data. Lack of visibility leads to obvious deployment
problems if the client cannot trust the servers.

Maturity over the years (2007-2015)

RMM Level 3 (a prerequisite for REST)

HATEOAS in a RESTful API… an example

• Require clients to know ahead of time how to process a message
received from the server other than understanding the MIME Type.
• Have human-readable documentation explaining how to construct URLs
for all the different resources.
• Have a big menu of options instead of an interconnected web. This
makes it difficult what one resource has to do with another.
• Let clients break and require them to fix, when changes are made to the
APIs or they undergo a redesign.
• Have Versioning.
Just like the web, RESTful Web APIs
should not…

• Stands for Representational State Transfer
• Resource-oriented – Uses URIs and Resources
• Uses HTTP Verbs
• HATEOAS (Hypermedia as the Engine of Application State)
• Uses HTTP Status Codes
• Takes other advantages of HTTP:
• Caching
• Security
• Statelessness
• Network layering (with firewalls and gateways between client and server)
REST Summary

RESTful APIs

Related slideshows

More Related Content

RESTful APIs