Hypermedia Markup

Hypermedia Client Maturity Model

There have been a number of attempts to define a maturity model for building RESTful services.  The idea of the maturity model is that is gives an indication how closely the service complies with the constraints of REST and hopefully demonstrates the trade offs to be expected when choosing to not follow a particular constraint.

Hypermedia Markup

One area that has not had as much attention paid to it is that of the client.  Although it is necessary for a service to be RESTful in order to build a system that exhibits RESTful characteristics, it is not sufficient.    The client needs to behave RESTfully or the coupling that the server tried to avoid will be re-introduced.

The following levels are my initial attempt to classify clients based on how coupled the client is to the service API.  Credit goes to @gblock for the idea and @robconery for inspiring us šŸ™‚

Level 0 ā€“ HTTP RPC

Client has server URLs baked into the code.  It knows the required parameters and the expected response including response body semantics and error codes.

In order to retrieve related information, the client must parse and interpret responses and build new URIs based on compiled in knowledge.

Level 1 ā€“ Fragile and fragmented hypermedia

Resources contain some links to related resources.  However, not all resources are accessible from the API root.  The client is aware of which resources contain which links and expects those links to be present. 

The client is aware of what type of resources are identified by embedded links.  Content is either described by a strict schema, or it is delivered using a generic format where the structure is known in advance by the client.

Failure to include links could break the client.   Changing the shape or contents of the response could break the client. 

Level 2 ā€“ Supple hypermedia

Clients can adapt to new or missing links.  Link relations are used to interpret the target resource and used in combination with forms and URI templates to construct requests.

Client application logic deals with http requests in an imperative manner. e.g.  Client makes request and in the same conceptual block of code handles the result.

This leads the client to have some expectations of the type of responses that might be returned from a certain request.  This introduces certain amounts of coupling into the interaction and requires abnormal responses to be handled explicitly.  e.g. 301, 304, 503, etc.

Level 3 ā€“ Reactive

Client uses the combination of link relation and response headers to determine how to interpret and handle server responses. 

Server responses are dealt with independently of the request.  The response is handled based on the mechanism used to invoke the link and the returned response.  This behaviour can be seen in a web browser when the resulting application page is identical, whether a request is made by clicking on a link in a page or typing the URI manually in the address bar.


Iā€™m interested to hear if people see value to this kind of categorization and whether there are factors that I have not considered or areas that need elaboration.

Related Blog