I agree with this, and in a way where I don't really see anyone who disagrees as a peer. We can agree to disagree, but it's condescending on my part.
On one team we once also came up with a compromise where we would use 2 status codes. 200 for all success, 400 for all errors. However I would prefer HTTP status codes just go away altogether. Those are for the web browser software to do things like navigation, not for APIs. Same with HTTP verbs.
Aside from the theoretical reasons why status codes aren't good for APIs, there's also a practical reason. Using the same status code for all intentional results is best because it allows the clients to write simpler error handling code. If they get a 200, then they also get a payload describing success or failure. If you get any other HTTP status, it's an unexpected or unknown error. If you were to instead use many HTTP statuses, each one comes in the known and unknown varieties, where the error description payload may or may not be there. In the simplest cases, this is equivalent. But in a more complicated case, where you many have more than 2 HTTP errors and also more than 2 application-level errors described in the payload, it becomes difficult to handle all the errors correctly.
Since I'm obsessed with telemetry data, as any seasoned engineer eventually will be, the conflation between HTTP error data and application error data is vexing in logs and telemetry. In older APIs I work with, the errors are all conflated in this way--errors were being tracked and categorized in some cases simply by their HTTP status. But there's 400s, and then there's 400s. There were unexpected 500s, and then there were 500s we understood and could have added data to. Sometimes a transient 500 could actually be understood as a 400. The results are not correct, and they would never be correct because it is not manageable.
People get so enamored with trying to make REST APIs into this rigorous thing. The REST thesis was an old academic trick where Fielding just described the way web browsers work, but changed all the specific nouns into spooky abstract ones. Most of the ceremony around HTTP trappings like status codes and verbs are there for the browser and are white elephants, obstacles, when trying to write an API.
> I agree with this, and in a way where I don't really see anyone who disagrees as a peer.
Oddly enough, I disagree with this, and in a way where I don't really see anyone who agrees as a peer.
Why? This approach fundamentally misunderstands the HTTP model. HTTP is not RPC. Again, HTTP is not RPC. Nor is it, as the article claims 'mostly just TCP with extra steps.' HTTP is a protocol for hypertext transfer which enables one to design applications not as APIs, but as state machines.
> If they get a 200, then they also get a payload describing success or failure. If you get any other HTTP status, it's an unexpected or unknown error.
That's just incorrectly written server software. A 400-series error may/should carry a payload. A 500-series error may/should carry a payload.
Use HTTP the way it is intended and designed, and these things are easy; misuse it and they are hard (and as you note, unmanageable). So … don't do that!
HTTP is the only protocol that's supported by browsers. I don't need hypertext in my APIs. I want RPC in my APIs. But browsers force me to use HTTP. So don't complain if my RPC APIs don't fit into the whole REST philosophy, as I don't care about philosophy, I'm engineer and I care about technical arguments. For all I care HTTP is a message protocol with headers to carry some attributes and some bytes in payload. For all I care, between client and server could be some proxies which can cache something (and thanks to HTTPS, I can be sure that all proxies are controlled by me). For all I care, between client and server could be some analytics software which will analyze traffic and might mark node as unhealthy based on 5xx HTTP codes or something like that. That's technical arguments and I do consider it.
Spending time arguing whether 400 or 404 or 422 is better fit is not engineering. You must return exact sting error code and that's about it. Whether that string error code wrapped in 400, 404 or 422 error does not matter. I, personally, use 400 errors everywhere because they're unlikely to occur from misconfigured reverse proxies and they won't confuse my clients which treat everything that's not 400 as gateway error. I think that I should start using HTTP 202 for all successful responses as well.
> I don't need hypertext in my APIs. I want RPC in my APIs.
You may want RPCs, but you need state transfer instead, for reasons which are too long to go into here but are explained pretty well in the original REST thesis.
> I'm engineer and I care about technical arguments
IIRC the REST thesis gives technical arguments against RPC, but in general the issue is that RPC is broken in a 'fallacies programmers believe about networks' way. The right way to perform actions across a network is not remote procedure calls, but transferring state representations.
> People get so enamored with trying to make REST APIs into this rigorous thing.
It is a rigorous thing, though. It's a standard, and one that has existed for a very long time.
> I would prefer HTTP status codes just go away altogether. Those are for the web browser software to do things like navigation, not for APIs. Same with HTTP verbs.
Verbs and status codes are fundamental for APIs that consume REST endpoints.
I totally understand thinking that vanilla REST is not the perfect model for every case. Maybe you should be using SOAP, or GraphQL, or HATEOAS. What a seasoned engineer shouldn't be doing is abandoning a shared specification and expecting everyone else to comply.
If I am using a third party's API and they serve nonsensical status codes (4xx when their DB is down, 2xx to let me know something failed), I will reach out and ask for them to fix their bug. If they tell me that the error code is deliberate, I will probably look for a more sensible vendor to work with instead.
On one team we once also came up with a compromise where we would use 2 status codes. 200 for all success, 400 for all errors. However I would prefer HTTP status codes just go away altogether. Those are for the web browser software to do things like navigation, not for APIs. Same with HTTP verbs.
Aside from the theoretical reasons why status codes aren't good for APIs, there's also a practical reason. Using the same status code for all intentional results is best because it allows the clients to write simpler error handling code. If they get a 200, then they also get a payload describing success or failure. If you get any other HTTP status, it's an unexpected or unknown error. If you were to instead use many HTTP statuses, each one comes in the known and unknown varieties, where the error description payload may or may not be there. In the simplest cases, this is equivalent. But in a more complicated case, where you many have more than 2 HTTP errors and also more than 2 application-level errors described in the payload, it becomes difficult to handle all the errors correctly.
Since I'm obsessed with telemetry data, as any seasoned engineer eventually will be, the conflation between HTTP error data and application error data is vexing in logs and telemetry. In older APIs I work with, the errors are all conflated in this way--errors were being tracked and categorized in some cases simply by their HTTP status. But there's 400s, and then there's 400s. There were unexpected 500s, and then there were 500s we understood and could have added data to. Sometimes a transient 500 could actually be understood as a 400. The results are not correct, and they would never be correct because it is not manageable.
People get so enamored with trying to make REST APIs into this rigorous thing. The REST thesis was an old academic trick where Fielding just described the way web browsers work, but changed all the specific nouns into spooky abstract ones. Most of the ceremony around HTTP trappings like status codes and verbs are there for the browser and are white elephants, obstacles, when trying to write an API.