API design is still relevant

I think it's a general issue with us, Engineers, we tend to think everyone sees the world through our same lens. I am one of those who think certain topics are common sense: look both sides before crossing the street, git push before going home and design your REST APIs properly.

It turns out, all of them are not as common as you think...

Recently, I was part of a project that consisted in a full rewrite of a mobile application in the Retail Banking space, when I say a full rewrite I mean it, we were redoing the backend and the app itself, after reviewing the architecture, data models, third party internal and external services, we started having a look at the API and it wasn't pretty, even worse, the new API would have to follow the old API's pattern, what was that pattern?, well all endpoints, regardless of the use, were POST endpoints, it was like GET, PUT, PATCH and DELETE did not exist at all.

They quoted "security reasons", they needed to send a token with the request and "it was not possible using GET requests" that's why they were only using POST. It seems like they didn't know about request headers.

In all my years, many or few, designing and building web applications and REST APIs, this is the first time I encounter such situation where all the tech leads agree the best thing to do is to have all the endpoints use POST and not only that, also all the result status codes were 200 (OK), if the request failed, everything was in the response payload, something like this.

{
    "code": 404,
    "errorCode": "NTF0040",
    "text": "resource not found"
    
}

They quoted "it's not an HTTP error, it's a business logic error, we don't want to mix both". But in reality, when you're working with REST, it's not about business logic or network, the semantics are always about the resources in question, what happened as a result of the action you wanted to execute on the resource.

REST has been out there for quite a long while and it has become one of the de-facto standards in the web, when we think of APIs, we unconsciously think of REST, even though there are more protocols for web APIs, we think of REST first and, to me, there's still some misconceptions and misinformation about the best practices to design REST APIs, everything implement it their own way!.

This is why I decided to put all my experience collected through years of working on the web, designing and implementing REST and other types of APIs into a book to help all those Coders, Software Engineers, Tech Leads and whoever wants to learn best practices or improve theirs in building REST APIs. At the time of writing this, I'm more than half way through it, consider subscribing to my REST 101 newsletter if you want to know more about the progress and the topics I'm covering and getting an initial pre-launch sample when it's ready.