středa 19. října 2011

REST maturity - 3 levels

Approaching the REST API implementation, there are some inaccuracies among programmers community. Some of them publish an API called REST which is in fact not REST because it violates some of it's constrains.

Leonard Richardson discussed "The Maturity Heuristic" at 2008 QCon speech. This can be viewed as levels of REST, or maturity levels of REST, or simply maturity of REST. I'd like to present my summary of his speech:

Level 0:
One URI and one HTTP method:
client can communicate with web app only through one URI, using only one method. This is like SOAP. We are using HTTP protocol here only as a container for our messages which carrying all the control information in the HTTP body.

Level 1:
Many URIs and one HTTP method:
it is level 0 with extended possibility - address concrete things. It's giving us opportunity to use only part of such web app (by addressing concrete thing through its URI) if we want. But we still have to put control information into HTTP body if we need further actions over URI.

Level 2:
Many URIs, each supporting multiple HTTP methods:
we can address desired resource and we can tell what to do with that resource by using HTTP verbs only. In the body there are no control information allowed. It can contain only content for addressed entity.

Level 3:
Many URIs, multiple HTTP methods and resources describing their own capabilities and interconnections:
if you enter some resource, it not only tells you what can you do with it. It tells you what are the actual URIs of possible actions, even what are the actual URIs of relevant elements(other URIs) and their actions. This is something called HATEOAS.
Best thing about level 3 is that you don't need manual to use it or to write client for that. You actually doesn't need to write client which is specific for some webapp because generic client can use all webapps which are at level 3.

So which of these mentioned levels belongs in REST?
The original author of REST, Roy T. Fielding clarifies common mistakes about REST API on his blog. He is very restrictive about what is REST and what's not - no levels allowed. If we apply his rules to levels above we can tell that only level 3 is REST. The other levels are not. So API which is below level 3 are not RESTful.

Žádné komentáře:

Okomentovat