As I continue my study on RESTful APIs I came across a REST Maturity Model in a presentation by Andy Wilkinson published at infoq. His topic was targeted toward documenting your API. He provided the REST Maturity Model as a basis to help establish what documentation methods work best at each level. Each level of the model builds on the capabilities of the previous model.
The model:
- Level 0 – XML-RPC SOAP – Client and server know each other intimately. All calls use a single endpoint.
- Level 1 – Separate Resources – Client and server do not necessarily share data contracts. Each resource has a different endpoint via a unique URI for each resource.
- Level 2 – HTTP Verbs – Client communicates with the server utilizing standard HTTP Verbs for CRUD actions PUT, POST, DELETE, GET, etc. The URIs, verbs and embedded JSON objects in the body replace the independent methods and SOAP packaged data contracts from Level 0.
- Level -3 Hyper Media – Server communicates what capabilities are available based on the current object state via hyper media links.
One of the things I find interesting is the continuous churn between having strongly typed data contracts and the converse. I’ve seen it at many different application layers, constantly changing over time. Remember strongly typed datasets? Strongly typed datasets were an extension of an ADO.DataSet such that it could be used like an object collection with nested collections based on relationships within a data store. Java had their own implementations as well.
Now we needed to solve the same problem connecting web clients to web servers, because they support HTTP protocol, and transfer objects from one system to the next. We started with a very powerful API of SOAP for handling these transactions. You could see a comparison to strongly typed datasets, with the addition of methods. Later, we find ourselves saying SOAP is too heavy. Let’s use REST methods. Now the client and the server both have their own definition of the world. Where the object models correspond, data is transferred. We did the same thing in Dot net by transferring DataTables into object collections. Where the column names matched the object properties, the data was transferred.
Both models have their pros and cons. If they didn’t, they wouldn’t both be so popular. RESTful APIs would simply be someone’s Thesis, not a movement. What is your position? Do you like the strong contractual relationship of the server and the client? What are the benefits you utilize by having a les strict relationship when it comes to data structures between the server and client? Drop a comment to get into the conversation.
Cheers,
Ben