RESTful interfaces are de facto standard in the modern web. When it comes to communication between distributed systems, probably almost every developer or architect would claim to rely on REST. However, according to the definition of Roy Fielding, a RESTful interface must meet the following four properties (as described in Part 2):

• Identification of resources
• Manipulation of resources through representations
• Self describing messages
• Hypermedia as the engine of application state (HATEOAS)

During my research for this article, I had the impression that the meaning of these four properties and the basic idea of REST were not specified until years after Fielding’s dissertation was published. This may have led to the fact that many interfaces do not fulfill the REST paradigm at all and are still falsely called RESTful.

The Richardson Maturity Model (RMM) is an interesting attempt to clarify the basic properties of an http-based REST interface. The model defines several levels (from 0 to 3), which describe the REST maturity level of a web service. In the following, the levels are explained using our customer database example.

The client reaches the WebService via a single URL and uses exactly one http method. The URL could look like this: /kundenDatenService. If the client wants to request data of a specific customer, he could send a POST request with the corresponding customer ID in the payload to /kundenDatenService. To query the customer orders, the client must send another POST request. The following figure illustrates the situation.

The client uses POST to send the request via http. The semantics of POST defined within http is completely irrelevant for the client. Martin Fowler, another recognized expert in the field of software architectures, speaks in this context also of tunneling over http. The client could also have chosen GET here.

The server models customers and orders as separate resources, which can be addressed via corresponding identifiers (i.e. URLs). The client still uses a single http method (e.g. POST) to tunnel over http. Again, the client could formulate the request via GET. The following figure demonstrates the communication flow, which is typical for level 1.

The server models customers and orders as separate resources and the client uses the correct http method. In our example the client requests the data. Therefore http GET is to be used here, as shown in figure 3.

So, the clients use pure http and do not have to tunnel. Martin Fowler emphasizes the following two advantages of level 2 compared to level 1: on the one hand, a strict separation between changing and requesting data can be achieved. Secondly, http error codes can be used, which makes error handling much easier.

“REST APIs must be hypertext-driven”: stresses Roy Fielding in this blog post. After the client has sent a request to the server, the server is supposed to provide information about the next possible actions besides the requested resource. It is thus hypermedia as the engine of application state (HATEOAS). The following figure shows an example of HATEOAS. A detailed consideration can be found in the second part of this series.

According to Martin Fowler, Level 3 is the last step on the way to a RESTful interface.

Richardson Maturity Model assigns basic REST properties to 3 levels and thus defines the RESTfulness of an interface. An interface can only be described as “restful” if it fulfills the HATEOAS principle (Level 3). While Level 0 and Level 1 interfaces are becoming increasingly rare in practice, Level 2 interfaces are very common. On the one hand, this shows that most REST properties are correctly implemented in the community. On the other hand, it is also an indication that HATEOAS has not yet fully arrived in practice.