RESTful levels

REST Maturity Model

Richardson created the REST Maturity model which specifies whether an API is “fully RESTful”. Most are not, and don’t necessarily have to be. But here is a rundown:

Level 0 - XML-RPC / SOAP

• One URI
• One HTTP Method

Level 0 is a very basic model where you simply sent an RPI (Remote Procedure Invocation) at a web site and it returns some data. It can be in XML, JSON, or any format with key-value pairs.

Level 1 - Add URIs

• Many URIs / Resources
• One HTTP Method

Level 1 is similar except now there are multiple resources in use:

http://www.yoursite.com/api/products/1234

http://www.yoursite.com/api/customers/0037

Level 2 - Add HTTP

• Many URIs/Resources
• Use of HTTP Verbs

In level 2 we add HTTP verbs: GET,POST,PUT,DELETE. There are others, but these four I will describe later.

Level 3 - Add HATEOAS

• Many URIs/Resources
• Use of HTTP verbs
• Hypermedia

In this level we add HATEOAS: Hypertext As The Engine Of Application State. This is how we send objects, but also some instructions in the reply describing what we can do next. For example, it may return something like this:

xml version="1.0"?>

<account>

   <account_number>12345</account_number>

   <balance currency="usd">100.00</balance>

   <link rel="deposit" href="/account/12345/deposit" />

   <link rel="withdraw" href="/account/12345/withdraw" /> 

   <link rel="transfer" href="/account/12345/transfer" />

   <link rel="close" href="/account/12345/close" />

 </account>

(from Wikipedia)

These hypermedia controls mean the REST client does not need to know how to use the service and instead can be guided by the responses. This is what is considered a “fully RESTful” service.