REST Maturity Levels

Manpreet Singh Bedi

10-Apr-2017
 Agenda
• REST Fundamentals
• HTTP
• Richardson Maturity Model
• Maturity Level 0: Not Restful / Swamp of POX
• Maturity Level 1: Resource Based URI’s
• Maturity Level 2: HTTP Verbs & Status Codes
• Maturity Level 3: HATEOAS (Hypermedia)
 REST
• REpresentational State Transfer
• REST is an architectural pattern for creating
services defined by Roy Fielding in 2000
• Not just limited to Xml – supports Json
• Focuses on Resources (nouns)
• Resources are exposed through URI’s
• Utilizes all HTTP verbs (GET, PUT, POST, DELETE)
• Supports caching
• Light Weight
 REST Principles
• Everything is a resource
• Every resource is identified by a unique
identifier
• Use simple and uniform interfaces
• Communication is done by representation
• Be Stateless
 REST Constraints (Contd.)
• Client Server
– Uniform Interface separates clients from servers
– Disconnected & independent from each other

• Stateless
– No client state is stored on server
– Each request contains enough context to process
the message
 REST Constraints
• Cacheable
– Clients can cache responses
– Responses shall define themselves as cacheable or
not

• Uniform Interface
– Defines the interface between client & server
– Simplifies & Decouples the architecture
– HTTP Verbs, URI’s, Response (Status & body)
 REST Constraints (Contd.)
• Layered System
– Client can’t assume direct connection to the end
server
– Intermediate layers may exist in-between

• Code on Demand
– Server can temporarily extend client by
transferring logic to it. Client executes that logic.
– Only OPTIONAL constraint
 HTTP
• is a TCP/IP based application layer protocol that
allows web-based applications to communicate &
exchange data.
• Stateless ( like REST )
• Connectionless
• Can deliver any data
• 3 sections
– Start line
– Header
– Body
 HTTP Verbs
Safe Idempotent Cacheable
GET

PUT

DELETE

POST

Safe - No side effects

Idempotent - Request can be done multiple times
Cacheable - Response can be cached

GET – from browser

POST – using html form tag method=“post”
PUT/DELETE – Ajax or JavaScript
 Richardson Maturity Model
• Developed by Leonard Richardson

• is a way to grade your API according to the

constraints of REST.

• The better your API adheres to these constraints, the

higher its score is.

• The Richardson Maturity Model knows 4 levels (0-3),

where level 3 designates a truly RESTful API.
Richardson Maturity Model
 Maturity Level 0:
Not Restful / Swamp of POX
• Uses its implementing protocol like a transport
protocol.

• Tunnels the requests & responses through its

protocol to indicate application state.

• One URI, one HTTP method (usually POST)

• Eg. SOAP & XML-RPC

Maturity Level 0 : Example
 Maturity Level 0 : Example (Contd.)
Hospital Appointment System
A. Get the open slots of my doctor on a date
Request:
POST /appointmentService
HTTP/1.1
[various other headers]
<openSlotRequest date = "2010-01-04"
doctor = "mjones"/>
 Maturity Level 0 : Example (Contd.)
Response:
HTTP/1.1 200 OK
[various headers]
<openSlotList>
<slot start = "1400" end = "1450">
<doctor id = "mjones"/>
</slot>
<slot start = "1600" end = "1650">
<doctor id = "mjones"/>
</slot>
</openSlotList>
 Maturity Level 0 : Example (Contd.)
Hospital Appointment System
B. Book an appointment
Request:
POST /appointmentService HTTP/1.1
[various other headers]
<appointmentRequest>
<slot doctor = "mjones" start = "1400"
end = "1450"/>
<patient id = "jsmith"/>
</appointmentRequest>
 Maturity Level 0 : Example (Contd.)
• Response – Booking successful
HTTP/1.1 200 OK
[various headers]
<appointment>
<slot doctor = "mjones" start = "1400"
end = "1450"/>
<patient id = "jsmith"/>
</appointment>
 Maturity Level 0 : Example (Contd.)
• Response – Error in booking
HTTP/1.1 200 OK
[various headers]
<appointmentRequestFailure>
<slot doctor = "mjones" start = "1400"
end = "1450"/>
<patient id = "jsmith"/>
<reason>Slot not available</reason>
</appointmentRequestFailure>
 Maturity Level 1:
Resource Based URI’s
• When your API can distinguish between
different resources, it might be level 1.
• This level uses multiple URIs, where every URI
is the entry point to a specific resource.
• Rather than making all our requests to a
singular service endpoint, we now start talking
to individual resources.
• Many URI’s, one HTTP method
Maturity Level 1 : Example
Maturity Level 1 : Example (Contd.)
So with our initial query, we might have a
resource for given doctor.

Request:
POST /doctors/mjones HTTP/1.1
[various other headers]
<openSlotRequest date = "2010-01-04"/>
 Maturity Level 1 : Example (Contd.)
The reply carries the same basic information, but each slot is
now a resource that can be addressed individually.
Response:
HTTP/1.1 200 OK
[various headers]
<openSlotList>
<slot id = "1234" doctor = "mjones" start = "1400"
end = "1450"/>
<slot id = "5678" doctor = "mjones" start = "1600"
end = "1650"/>
</openSlotList>
 Maturity Level 1 : Example (Contd.)
With specific resources booking an appointment
means posting to a particular slot.
Request:
POST /slots/1234 HTTP/1.1
[various other headers]
<appointmentRequest>
<patient id = "jsmith"/>
</appointmentRequest>
 Maturity Level 1 : Example (Contd.)
Response: Success

HTTP/1.1 200 OK
[various headers]
<appointment>
<slot id = "1234" doctor = "mjones"
start = "1400" end = "1450"/>
<patient id = "jsmith"/>
</appointment>
 Maturity Level 2:
HTTP Verbs & Status Codes
• When your API uses HTTP verbs, it might be level 2.
• Many URI’s, each supporting multiple HTTP methods.
• Rules:
– Use appropriate method for the purpose intended.
– Don't use a single POST method for all.
– Make use of GET when you are requesting resources.
– Use the DELETE method when you want to delete a
resource.
– Also, use the response codes of your application protocol.
Don't use 200 (OK) code when something went wrong for
instance.
Maturity Level 2 : Example
 Maturity Level 2 : Example (Contd.)
• Now we will use GET method to retrieve list of
slots:

Request:
GET /doctors/mjones/slots?date=20100104&status=open
HTTP/1.1
Host: royalhope.nhs.uk
 Maturity Level 2 : Example (Contd.)
The reply is the same as it would have been with
the POST of maturity Level 1
Response:
HTTP/1.1 200 OK
[various headers]
<openSlotList>
<slot id = "1234" doctor = "mjones"
start = "1400" end = "1450"/>
<slot id = "5678" doctor = "mjones"
start = "1600" end = "1650"/>
</openSlotList>
 Maturity Level 2 : Example (Contd.)
To book an appointment we need an HTTP verb
that does change state, a POST or a PUT.
I'll use the same POST that I did earlier.
Request:
POST /slots/1234 HTTP/1.1
[various other headers]
<appointmentRequest>
<patient id = "jsmith"/>
</appointmentRequest>
 Maturity Level 2 : Example (Contd.)
• Response : Success
HTTP/1.1 201 Created
Location: slots/1234/appointment
[various headers]
<appointment>
<slot id = "1234" doctor = "mjones"
start = "1400" end = "1450"/>
<patient id = "jsmith"/>
</appointment>
 Maturity Level 2 : Example (Contd.)
• Response: Some error

HTTP/1.1 409 Conflict

[various headers]
<openSlotList>
<slot id = "5678" doctor = "mjones"
start = "1600" end = "1650"/>
</openSlotList>
 Maturity Level 3:
HATEOAS (Hypermedia)
• Hypermedia As The Engine Of Application State
• Level 3 response directly returns the URI of the
resource, that can be used for the next operation.
• Hypermedia controls tell us what we can do next,
and the URI of the resource we need to
manipulate to do it.
• Rather than us having to know where to post our
appointment request, the hypermedia controls in
the response tell us how to do it.
Maturity Level 3 : Example
 Maturity Level 3 : Example (Contd.)
We begin with the same initial GET that we sent
in level 2

Request
GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1
Host: royalhope.nhs.uk
 Maturity Level 3 : Example (Contd.)
But the response has a new element:
HTTP/1.1 200 OK
[various headers]
<openSlotList>
<slot id = "1234" doctor = "mjones" start = "1400" end = "1450">
<link rel = "/linkrels/slot/book" uri = "/slots/1234"/>
</slot>
<slot id = "5678" doctor = "mjones" start = "1600" end = "1650">
<link rel = "/linkrels/slot/book" uri = "/slots/5678"/>
</slot>
</openSlotList>
Each slot now has a link element which contains a URI to tell us how to
book an appointment.
 Maturity Level 3 : Example (Contd.)
The POST would again copy that of level 2

Request:
POST /slots/1234 HTTP/1.1
[various other headers]
<appointmentRequest>
<patient id = "jsmith"/>
</appointmentRequest>
 Maturity Level 3 : Example (Contd.)
And the response contains a number of hypermedia controls for different
things to do next.
HTTP/1.1 201 Created
Location: http://royalhope.nhs.uk/slots/1234/appointment
[various headers]
<appointment>
<slot id = "1234" doctor = "mjones" start = "1400" end = "1450"/>
<patient id = "jsmith"/>
<link rel = "/linkrels/appointment/cancel" uri = "/slots/1234/appointment"/>
<link rel = "/linkrels/appointment/addTest" uri = "/slots/1234/appointment/tests"/>
<link rel = "self" uri = "/slots/1234/appointment"/>
<link rel = "/linkrels/appointment/changeTime" uri =
"/doctors/mjones/slots?date=20100104@status=open"/>
<link rel = "/linkrels/appointment/updateContactInfo" uri =
"/patients/jsmith/contactInfo"/>
<link rel = "/linkrels/help" uri = "/help/appointment"/>
</appointment>
REST Maturity Levels
 Summary
• Level 0:
– Single service endpoint for all requests

• Level 1:
– API can distinguish between different resources
– tackles the question of handling complexity by
using divide and conquer, breaking a large service
endpoint down into multiple resources.
 Summary
• Level 2:
– API uses appropriate HTTP verbs & status codes
– introduces a standard set of verbs so that we
handle similar situations in the same way,
removing unnecessary variation.
• Level 3:
– Returns the URI of the resource, that can be used
for the next operation.
– Introduces discoverability, providing a way of
making a protocol more self-documenting.
THANK YOU