Please Give It A REST!

A regular stressful day in the life of a software developer. I was communicating a module we needed to quickly put together. The team was not exactly new. We had a backend guy, and a front-end guy. Interface was designed and agreed upon, we needed to make it quick, we just defined the resources and said that we need the ‘standard CRUD operations done via REST’ on them. And we got down to work.

When everyone reverted that they were done, we sat down to quickly integrate and test, but the front-end and the backend refused to talk, we got the 404, not found. Well, it should have been simple, we had very clear instructions; the resource names and that they were REST.

Or so I thought. REST, the standard, arguably most popular of the web service protocols out there should have made it very easy for the backend and frontend to talk to each-other. But no. Turns out that there are (still) huge misconceptions around REST; there are so many among us who believe that abominations like ‘getCustomer’ and ‘createCustomer’ (yeah, you guessed it write, the HTTP method was ‘GET’ for this one too) are ‘resources’ and are valid REST.

Oh please, give it a rest.

Not the first time have I encountered this, and it would not be the last either. I thought we were over this. But no, I had fallen for it, assuming that common knowledge is common. It is not.
Well, these ‘divergents’ among us, are not totally wrong in assuming what they write is REST, it could probably be referred to as a form of REST. They are on HTTP at least, someone could certainly fit the level-0 in Richardson Maturity Model to it. But this type of API modelling does not really help integrations, has no standard understanding nor predictable way of implementation and yet we tend to stick with it.

The level-2 is where we need to be with REST, as a basic understanding and expectation from APIs: with Verbs and Resources. It conveys a very clear message as what to expect
from the interface. While Level-3 or HATEOAS with a hypermedia client, or if you are so security conscious making the URLs opaque, would be a dream implementation but for a team struggling with ‘resources’ it feels far-fetched. So level-2 it is.

I have seen that there seem to be a whole lot of people with this kind of confusion around, entire applications built with just GET calls for everything, even for inter-service and frontend-backend communication. I wonder at times what could have caused this confusion, and popularity of Spring’s for REST implementation comes to mind time and again. It is also an observation I have made over time, those who think ‘resources’ also tend to be Jersey (JAX-RS) users at some point in time and the other class seems to be comprised largely of Spring users for their REST implementation.

Probably it makes sense, Jersey as a framework leaves little room for the idea of method-wise resource names, you tend to define the resource at the top of the class (or resource!) and HTTP methods are just marked below. Although you have the option of marking each of your method differently with an additional @Path annotation, the trend is not seen as much and people are forced to think in terms of resources and verbs. Whereas the Spring’s implementation of REST is basically the Spring MVS’s controllers and request handling used to simulate how a REST service will work. Although Spring 4 introduced the @RestController it did little to enforce the resource behaviour as did @GetMapping, @PostMapping and the siblings defined in Spring boot; the method implementations are still standard (or implied) @RequestMapping from Spring MVC and coming from there, people may tend to think a need to override the handling and define the java method name in the path, for some reason. Well, I would not know for sure but this seems like a logical explanation for the trend observed.

Now how do we convey to everyone that they do not need to define different paths and let the HTTP verbs do their job is a challenge. This post is just an attempt.

No comments:

Post a Comment

We need to talk, says one microservice to another

‘But how?’ asks the other service! Ever wondered how we communicate? One would not believe how complex and multi-step process it is. It in...