In this post I will talk a bit about the holy grail of REST (Representation State Transfer). There is the “Richardson Maturity Model” to classify REST. The higher your level the better you are. Let’s start by telling a bit of history, how I went through some of these levels.
At university the first thing we had to build as a team was a chat program. We took the straight forward approach. Create some services which communicate over a TCP/IP stream with each other. This was our first application which was distributed. Most of the time in university we did build applications, which only communicate with the file system and the console. The problem with the TCP stream is, it does not work well in the internet. In most cases the ports are blocked by a firewall for security reasons.
Some semester later we learned about that “awesome” technology called Service Oriented Architecture (SOA). This solved the problem with the blocked TCP ports. All data is enveloped in XML and tunneled through the HTTP ports, which are mostly open. If you did something like that, you are probably at least on Level 0. 🙂
In one company I worked for, they sent every data over a TCP/IP abstraction layer. This was probably Level -1. My task was to create a project from scratch. I ended up using SignalR to communicate between client and backend. With SignalR I introduced resources to my application. So I had an URL-resource for people and different resources for competition management or other data. I leveled up again to Level 1. Afterwards I think the hardest part was to get management to approve my architecture and technology.
In the same project I often had the problem with saving entities. I only knew that if an identifier was not set, it was created, otherwise it was updated. For creating an entity we had to do things differently than for updating it. That bugged me back then and I didn’t have a solution because I had no time to educate myself and I had my hands full with getting people to understand what and how we were doing HTTP. I knew that HTTP possessed verbs like “POST”, “PUT”, “DELETE” and many more, but SignalR didn’t support that. I didn’t make the connection in my brain. But sometimes people use good technology just wrong. So I should have used a controller of ASP.NET for our RPC (Remote Procedure Call) calls. Only for live messaging I should have used SignalR. This knowledge brought me up to Level 2.
This sounds really good but it was not the end of the road. The project I worked on had really few developers (one) and my colleague with the vast amount of domain knowledge had to maintain our legacy product. One day, management figured we had to do a release at the end of the month. The result of this short release date with too few features implemented resulted in me having 4 other developers to work with. In our meetings we explained the tickets and then we implemented them in the sprint. Several times our frontend guru came in and asked me about the workflow for the user. I rolled my eyes but I knew he can’t learn all processes in one month. Took me several years and I still don’t fully understand it. I implemented the backend and the process worked there. One day he broke the UI, the other day I broke the backend, because of the missing understanding. I couldn’t solve the real problem back then. But now I know that writing a descriptive API helps . The best example comes from HTML in my point of view. In Level 2, when we do a call to a resource, we get the data of the resource. If we now add control structure like in HTML, we level up to Level 3. This way the UI guru does not need to know what to do when. My API tells him!
I hope I could give you an example of what to improve in the REST-API you are writing and maybe you see some similarities. Feel free to share your experiences or ask if some things were not clear!