Richardson Maturity Model provides step by step way to understand the basic ideas
behind RESTful thinking. This is more of tool to understand concepts and not
something that should be used in some kind of assessment mechanism for your
REST api. A model (developed by Leonard Richardson) that
breaks down the principal elements of a REST approach into three steps. These
introduce resources, http verbs, and hypermedia controls. Each level is a condition for the next, so to qualify for
level 3, the only way for a service is to also support levels 1 and 2.
Level 0
The starting point for the model is using HTTP as a transport
system for remote interactions, but without using any of the mechanisms of the
web. Essentially what you are doing here is using HTTP as a transport mechanism.
It will use only one entry point (URI) and one kind of method (in HTTP, this
normally is the POST method). Examples of these are
SOAP and XML-RPC.
Level 1 - Resources
This is first step towards becoming more RESTful in the
Richardson’s Maturity Model. So now rather than making all our requests to a
singular service endpoint, we now start talking to individual resources.
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. Instead of going through http://example.com/employees,
you actually distinguish between http://example.com/employee/1234 and
http://example.com/employee/6789. Still, this level uses only one single HTTP method
like POST.
Level 2 - HTTP Verbs
At Level 2, Don't use a single POST method for all, but make use of GET when
you are requesting resources, and use the DELETE method when you want to delete a
resources. GET is safe and idempotent operation, that is it doesn't make any changes
to the state of any resource. This allows to invoke multiple GET safely in any
order and still get the same results each time. An important consequence of
this is that it allows any participant in the routing of requests to use
caching. HTTP includes various measures to support caching, which can be used
by all participants in the communication.
The important part of response is the use of an HTTP response
code to indicate something has gone wrong. Don't use 200 (OK) code when something went wrong for instance. Rather
than using a return code of 200 but including an error response, at level 2 we
explicitly use some kind of error response code. It's up to the api designer to
decide what codes to use, but there should be a non-2xx response if an error
crops up. Level 2 introduces using HTTP verbs and HTTP response codes.
Level 3 - Hypermedia Controls
The final level introduces
something that you often hear referred to under the acronym of HATEOAS
(Hypertext As The Engine Of Application State). The point of hypermedia
controls is that they tell us what we can do next, and the URI of the resource
we need to manipulate to do it. One obvious benefit of hypermedia controls is
that it allows the server to change its URI scheme without breaking clients. As
long as clients look up the linkrels URI then the provider can juggle all URIs except
the initial entry points.
A additional benefit is that it
helps client developers explore the protocol. The links give client developers
a hint as to what may be possible next. Similarly it allows the server team to
advertise new capabilities by putting new links in the responses. If the client
developers are keeping an eye out for unknown links these links can be a trigger
for further exploration.