> 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.
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!