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

Browsing the Web 101

• 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 OKContent-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.1Host: www.youtypeitwepostit.com Request

Response


<!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.1Host: www.youtypeitwepostit.com Request

Response

HTTP/1.1 303 See OtherContent-type: text/htmlLocation: http://www.youtypeitwepostit.com/messages/5266722824890167

POST /messages HTTP/1.1Host: www.youtypeitwepostit.comContent-type: application/x-www-form-urlencodedmessage=Hello!&submit=Post

Request

Response


GET /messages/5266722824890167 HTTP/1.1Host: www.youtypeitwepostit.com Request

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 0

RMM Level 1

RMM Level 2

RMM Level 3 (a prerequisite for REST)

HATEOAS in a RESTful API… an example

HATEOAS in a RESTful API… an example

HTTP Verbs (Methods)

HTTP Status Codes

• 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

Documents

RESTful APIs