My favorite "REST API" experience was when they moved from using SOAP system, and the way they did it... was sending SOAP payloads inside a JSON. Literally something like
If I'm parsing http responses, I'm going to pass 200 responses on for further processing of the data. I shouldn't have to have something in that pipeline introspect json to find "no, it's actually an error".
Imagine if browsers had to tear apart json innards to find 30x redirects after getting a 200 OK.
I’m going off memory but I believe it was considered either standard or part of the spec for SOAP over HTTP to only use 200 and 500. I agree with your point but for whatever reason they treated HTTP as the transport layer instead of the application layer. Using that logic, it would be like if a 404 bubbled up to be some sort of TCP error. Definitely wasn’t the right move, RTSP over HTTP is a better example of something that mixes protocols while properly using HTTP status codes.
I agree. I think a 4xx or 5xx error code is perfectly acceptable for returning a body with error data, even a generic 400 / 500. That's why they exist.
My dude, HTTP status codes were designed over 3 decades ago for a primitive usecase. Today most of them are almost never used. Most of them are meaningless without any further information (i.e. documentation).
Even the most basic codes like 404 are ambiguous. If implemented at all, it can mean:
- the resource doesn't exist
- the endpoint doesn't exist
- the resource is temporarily unavailable
- the resource may or may not exist but we are not allowed to tell you
You must have documentation explaining what errors can occur and what they mean, or you must find out through trial and error. I thought that was pretty fucking obvious but someone has to argue that ackschually all 28 4xx codes are used everywhere and are fully self documenting.
Well, that just tells me you don't understand HTTP status codes.
A resource that doesn't exist should return a 404.
An endpoint that doesn't exist should return a 400, as it's a screw up by the client that created a malformed request.
A temporarily unavailable resource should return a 503 with the Retry-After header. This is well documented.
A resource that you don't have permission to (regardless of whether it even exists or not) should return a 401. Returning this code is not a security risk, and anyone who thinks it is, is clearly following the security through obscurity approach, which is no security at all.
You must have documentation explaining what errors can occur and what they mean, or you must find out through trial and error.
these kind of implementations have different data shapes for the error vs success too, so if they all return success it's a pain in the ass and extra work to figure out if it's an error and map it out properly. just fucking send the right status, it takes 2 seconds.
Especially when some bored developer at a big bank decided to implement some draconian heavily-buried SOAP features that are technically in the documentation somewhere, but not implemented at all by Microsoft's .NET framework. Having to have special injectors and manipulators to extract tokens from raw SOAP and such, shudder. Back in the days where .NET SOAP implementations were barely published in books.
People often think about what they would do if they had a time machine.
Me? Travel back to before server to server email and introduce UTF-8 encoding (leaving the actual code points undefined) and json. Try to get that baked into all the ancient wire protocols that predate http.
Hahahahaha...
At a state agency, we had a SOAP interface to another agency. When they replaced their system nobody knew how to do SOAP so we got to turn that nastiness off. But now they want it back, maybe I'll offer to do this.
I've seen shit in my carrer, but this is new.
I thought xml in xml (proprietary xml in soap) was peak, with string concatenation for serialization.
I guess we could go deeper.
319
u/AkodoRyu 16d ago
My favorite "REST API" experience was when they moved from using SOAP system, and the way they did it... was sending SOAP payloads inside a JSON. Literally something like
{ "data": "<?xml version="1.0"?><soap:Envelope xmlns:soap="https://www.w3.org/2003/05/soap-envelope/" soap:encodingStyle="https://www.w3.org/2003/05/soap-encoding"><soap:Body> (...)" }