How much RESTful is your API

We all have a tendency to say and assume that our API is RESTful as soon as we expose our services using HTTP with JSON/XML and applying some conventions around the HTTP verbs (GET, POST, PUT, DELETE, etc.). However, this assumption is not correct. I don't want to dig in the REST architectural style to show why this assumption is  incorrect; instead I want to share something that I learned recently while I'm preparing for my MCSD certification in Web Apps, in particular while studying for exam 70-487: The Richardson Maturity Model.

The Richardson Maturity Model describes four levels of maturity for services

• Level 0. Use HTTP as a transport protocol by ignoring the capabilities of HTTP as an application layer protocol. Level 0 services use a single address, also known as endpoint and asingle HTTP method, which is usually POST. SOAP services and other RPC-based protocols are examples of level zero services.
•  Level 1. Identify resources by using URIs. Each resource in the system has its own URI by which the resource can be accessed.
• Level 2. Uses the different HTTP verbs to allow the user to manipulate the resources and create a full API based on resources.
• Level 3. Although the first two services only emphasize the suitable use of HTTP semantics, level 3 introduce Hypermedia, an extension of the term Hypertext as a means for a resource to describe their own state in addition to their relation to other resources.

Martin Fowler has a great post in his blog describing in detail these four levels.

I would risk to say that most of us, when using the Web API project template provided in Visual Studio and following the typical recipes, or using the scaffolding generated code, most of the time we are building services at level 2. If we want our services at level 3, we need to introduce Hypermedia elements in our payloads. Maybe we should look to HAL - Hypertext Application Language, which is a simple format that gives a consistent and easy way to hyperlink between resources in our API.

Roy Fielding, the author of the doctoral dissertation that describes REST, considers that level 3 is required in a REST architectural style. However, I think I'll continue to say that "our API is a RESTful API", even though my services are at level 2.