You must log in or # to comment.
{ "ok": false }{ "ok": false }wouldn’t that be more like
new Promise(() =>{ return { "ok": false }; })
{ "ok": "false" }{ "ok": "no" }{ "false": "ok" }$false=true
{ "OK": "Ah ah ah, you didn't say the magic word." }
error = true with no description or answer is basically ten years of searching stackoverflow and reddit threads for an answer.
Or a link to a thread on microsoft answers that 404s
that’s the worst due to how microsoft answers redirects work making it impossible to go back to the previous page.
Please, please, please, PLEASE return error-codes and problem-details.
Here’s the RFC: https://www.rfc-editor.org/rfc/rfc9457.html
Nightmares.
This looks so over-engineered. Most of the time you only need an error message. Make the message clear enough so that it can be shown to the end user.
Why even use HTTP, when you can just send bytes directly over the physical network card, right?
Because standards make it better for everyone. You’ve no idea when, who or in what context the error will happen or be received by.
It takes so little to return ProblemDetails, and improves the experience of devs using your API so much. Just do it. Stop thinking up edge cases and faffing about with excuses. Do it.
I think the challenge is that it looks like a lot of other ‘standards’ I’ve seen: on one hand tediously specific yet on the other hand, so open ended as to largely defeat the point.
Every problem must have a ‘type’. Ok, fine, so what are the semantics of the ‘problem type’? Well, nothing in particular, just has to be defined, but it might be nice if it’s a url telling a human about your own human thoughts on the type. Also, if you encounter multiple ‘errors’, you need to omit any that you arbitrarily fail to group into the same ‘type’ which shouldn’t be subjectively too vague either, so don’t think about making catch-all types so you don’t have to discard some of the errors.
You can’t count on the members, and a problem type may arbitrarily ‘extend’ to completely rearrange those members into members of child objects instead, but that’s really all up to the backend to decide however they want to arrange it, with no prescribed standard for error bundling, but an example of how a backend could voluntarily implement such bundling as an implementer specific extension if they like, but again, don’t bundle errors that shouldn’t seem to be of a common type…
Also I think it’s funny that they say do this in the name of being a good web citizen, but then say send this new mime type down, client’s Accept header value be damned.
It purports to drive toward “machine-readable” problems but it seems like there’s not much actually actionable and the client has to in practical terms do a bunch of bespoke handling to deal with a backend that is still pretty much open to do whatever they like.
It has a couple of reasonable seeming examples, but nothing that would make me think “Oh, you implement RFC 9457? Then I already have error handling code ready to go!”
I’ve seen all sorts of complex errors generated by backends that have all sorts of features like this and more (error messages with parameterized string values, json pointers to specific problematic pieces of the client request. However people just want a human readable response to pass along. I could imagine the example ‘pointer’ being useful to map error details to a client maintained form, but that’s not even the ‘standard’, just a random example ‘extension’…
Exactly! This is why the server should just send a clear error message. 99% of the time the client just wants to show the error message to the end user, and not have to wrangle all kinds of normalized data into one.
I wouldn’t even mind wrangling some normalized data, but it doesn’t seem very normalized in their examples.
Their first example suggests “great, there’s a human appropriate title and detail, and maybe this standard will say you should at least have those and they should be ready for pass through to a human operator”, with extensions providing room for more sophisticated behavior.
Then the second example, no more top level detail, now there’s an ‘errors’ array, and detail is under the children (which they don’t formally describe the concept of reparenting attributes, just incidentally showing it in an example of what an implementation could do with ‘extensions’). Well, at least I can still pass through the details if I find them and it will make sense right? “must be a positive integer”… Ok, nope, error information that requires the client to process a json pointer in order to manufacture some sort of actionable feedback. Again, this could be a neat optional feature, but a generic core client really has nothing they can bite into that generically applies to the standard.
The cited RFC I think is close to some ideas but softens it by trying to be open ended. If it specified mandatory top level “detail” member that is reasonably directly informative to a human operator without further processing, great, I know exactly where to find it even if I don’t otherwise understand your problem type. Mandate that errors may be a collection under an ‘errors’ list, but otherwise identical to top level? Cool. Saying that here’s some recommended members, but they are all optional and the behavior is really up to you, and you can just freely change everything you want and call it ‘extensions’… Just not prescriptive enough despite the long words…
Aaagh! Getting some random old person flashbacks.
Kids. I r-remember a day… You won’t believe this… I got a 404 error page… It was otherwise a normal 404 page with a normal message on it, but it had a giant ad on it… like “while you’re here, how about you buy this stuff”… It was hell… You’ve got no idea how lucky you kids are with uBlock…
I was going to say that sounds like situation normal by the 2020s… Until you said uBlock.
Fun story close to a decade ago we were attempting to upgrade our batch scheduler called Tidal to version 6x which had a RESTful API.
One of the reasons we dropped the product was because we were getting 200 status codes meanwhile the output was a java dump of an error message.
They were adamant that this was an us problem, no matter how much I tried to explain to them with numerous links explaining to them that if something has a 200 status code that should mean things worked.
They argued that the 200 meant we were hitting the API fine. We would have to write code to read the return for if it was a error or not. I still don’t think they understood how stupid they were, even all these years later.
I have had that argument repeatedly with people. People insisting that HTTP error codes are “transport layer” and it’s “wrong” for an API to hijack them to report “application level issues”.
No, the whole point of “REST” was to map application semantics to HTTP in a way that actually normalizes some things like error handling and expectations around whether an operation could be expected to be idempotent and make the namespace navigable.
At one point my work announced a person who was an external hire to be the ‘API genius’ to set my company straight. He came from a super reputable well known company so of course he just the smart guy to fix our technical mess. He had sent a message saying that he had reviewed the teams API and concluded they were not restful. I had a glimmer of optimism, that someone recognized as authoritative would call the RPC style HTTP usage that always returned 200 and steer toward sanity, or at least honesty. No, his feedback was that was all fine, but REST does not use JSON, REST uses Protobuf, so they need to change to Protobuf to claim to be REST. Of all the what the hell I could have predicted, that one was not in my book…
A real “API Genius” would be complaining that your API doesn’t include HATEOAS, even though I’ve never once seen an API be used in that way, and few of the big tech APIs actually use it even though they call their APIs RESTful.
My particular project did embrace HATEOAS, just other teams did not.
The number of people talking about REST without having read the wikipedia page is astonishing. Roy Fielding’s dissertation on the subject might be of interest, but that’s from 2000 and absolutely not webscale.
(Edit: /s if that wasn’t immediately obvious)
It’s ok, as long as you make sure to use mongodb it will be webscale no matter what. But if you date use anything else, it won’t be.
The quote “brimming over with wrongability” comes to mind.
To further your point and remembering my asinine discussions with the vendor.
Fine. I accept what they said. Then the return code should be a 5xx code not a 200.
I genuinely wonder if they addressed their fuckups.
Side note their updated desktop client (because of course new version didn’t have one so they had to write one fast) was a java client that needed 16gb of ram to run marginally well lol
Yep, I’ve got one of these at work now. Technically, 200 can make sense here if you’re using HTTP as RPC transport, as the server relayed the request to its handler and returned the outcome, but damn if it’s not annoying to actually process the response.
I’ve also seen a lot of devs tie themselves into knots trying to map various execution types to the “semantically correct” HTTP code, but the thing is the abstraction of HTTP is not based around RPC and it’s ultimately a pretty weird fit that we’ve somehow come to view as normal.
Then just return a 500 - Server error. Nice and obscure.
The ability to separate “something wrong with what you sent” (4XX) and “something wrong on the server” (5XX) is very valuable in itself.
Yep
- 2xx - it’s good
- 3xx - not here cunt
- 4xx - you don fucked up
- 5xx - we fucked up, whatever you do aint changing shit.
1xx - We’re still working on it
And then there’s 418
good old 418, always appears when you really want a cup of coffee
The number of times I’ve gotten 5xx codes for bad requests is annoyingly high.
Fair. But they still fucked up so at least that’s on them
I guess it’s like a retail worker apologising excessively because of trauma.
Respond to everything as a teapot
It’s not us, it’s you
It’s us: 5xx
It’s you: 4xx
JSON API almost always means “not REST”. In other words, it works as intended.
I don’t wanna be pedantic but most things we call REST aren’t REST. The original definition of REST is what we typically call HATEOAS. So when you say JAON API almost always means not REST you need to qualify that.
how would you return metadata or more detailed error codes?
returning a 400 never prevented me from adding more info to the response
However you like, REST doesn’t dictate anything there. Just be consistent and use hypermedia.
JSON APIs almost never follow REST because they almost never use JSON as hypertext. Worse, no complete stable hypertext JSON standard exists. There’s JSON-HAL, but it lacks a way to represent resource templates (think HTML’s
<form>).Therefore, with JSON APIs ignoring one of the most basic idea behind REST, why would anyone expect them to follow another idea of REST - consistency?
REST is a deceptively simple concept. Any time you build an HTML website a human can navigate without consulting documentation, you’re doing it better than vast majority of swagger documented corporate APIs.
Fun fact, I actually did implement JSON-HAL and peers wondered why I was putting this “silly _links dictionary member” in there.
I’ll say I’ve seen other REST APIs using json and at least honor the concept of hypermedia, but in a useless way. They’ll have links specified, but even within their API no consistency on what dictionary keys would refer to related resources versus data.
The argument probably goes something like " if you adhere strictly to REST the error codes are all you need" and then metadata can be sent in response headers.
how should a REST API respond to the client sending a URL the ends in a string instead of a numeric ID? like api.social/users/ceeforayteen instead of api.socail/users/11037
I would do a 400 (Bad Request). Then, with varying amounts of detail depending on the scale of the project and the framework capability, the response body would be something like: { “error”:true, “reason”: “validation”, “detail”: “user id should be numeric” }
that’s what i would do too—a JSON response. or is that not what “JSON API” means?
A RESTful service is (usually as of today) a JSON API. They aren’t mutually exclusive things.
There’s no black and white definition there.
However, when someone is creating a RESTful service, they’re stating that they’ll be paying mind to HTTP Verbs and status codes as a fundamental part of their design.
In the original image posted, that dev clearly wasn’t paying mind to the HTTP layer and as such a commenter called it just a “JSON API”, which is the catchall, ugly, Wild West, typical way of doing things (always return 200, errors are in the json).
Once again tho, it’s not black and white. Others can and will disagree and want to be pedantic. I’ve been a professional dev for 35 years, devs love to argue abt this shit.
devs love to argue abt this shit.
Tabs vs spaces comes to mind.
devs love to argue abt this shit
Devs and standards have a contentious relationship.
If I develop something, I obviously know what works best for me, so I don’t want to be constrained by some dumb standard. If someone else doesn’t follow them and it makes things harder for me, they’re a clueless fuckwit that shouldn’t be allowed near a computer ever again.
Yes, that’s a double standard: I don’t even have a standard when it comes to handling standards.
It’s still just another type of ID so you can do lookups on it. Nothing would change. UUIDs are used all the time.
Depends on the verb and the application. If the string is valid 200, if it isn’t 400, 404.
Been having similar case with dev teams who have coded every error to be 500. User typed the wrong URL? 500. User tried to access a page without logging in? 500… Makes detecting real errors a pain
And on the other side of this are JS devs that check for neither error response codes or error messages, and write an error into their own data as if it’s the result they were after.
Always fun to see GET /orders/{error : “invalid branchID provided”} in your logs.
I’d easily take that over ‘200 for everything’. If at least errors are distinct from success, I’d take that as a win. My standards have been lowered by so many ‘200 for everything’ backends…
Makes all issues their problem. Clearly it’s not a 4xx error so not something the client did wrong.
I would argue that in your application, a wrong URL is a sever error. That error being improper handling of a client error.
I’m not a web dev, but had a similar problem with a niche compiler I used to develop.
We were pretty good at validating invariants at the mid and back-end. This meant that most user errors got reported as internal errors. Generally, these errors were good enough that users were able to get used to reading them and fix their code.
It was next to impossible to actually get users to file bugs about this. Our internal error messages started with a banner that read “THIS IS A BUG IN <compiler name>. PLEASE REPORT TO <support email address>”. Despite that, whenever we actually got a bug report, it would inevitably start with “I’m pretty sure this isn’t actually a bug in the compiler, but I can’t figure out what I am doing wrong in my code”.
I would argue that in your application, a wrong URL is a sever error. That error being improper handling of a client error.
That’s certainly an unusual take. If you are a backend to HTTP and something throws a completely bogus URL out of left field at you, that’s not by any means a backend error.
I guess your take is that it might be some sort of usability issue or such because if 95% of clients try to hit the same non-existant URL, that probably means there’s some reasonable expectation that you should do something about the URL. However that’s relatively more rare a sort of ‘invalid URL’ scenario. The vast vast majority are some sort of scanners trying bogus crap, followed by an impossibly diverse set of typos and peculiar one-off assumptions that you can’t possibly reasonably cover.
If it’s not a backend error, you shouldn’t be throwing a 5xx error code. Since you are throwing a 500, you have a server bug; even if that bug is simply “sends incorrect error code”
Ok, got you, thought you were saying a bad url from client was inherently a backend mistake.
Congratulations! You failed.
no worries! a small failure is the first step on the way to a really really big failure.
GraphQL makes this same mistake
That’s true, but for a good reason. GraphQL is transport agnostic, so using HTTP status to represent errors doesn’t make sense. HTTP is just a carrier for GraphQL, and the status code represents whether or not the HTTP part was successful.
If only that were true. They are intimately connected and to pretend otherwise is laughable to me
What do you mean? You can literally run GraphQL without HTTP. This isn’t just a GraphQL-ism, gRPC also does it https://grpc.io/docs/guides/status-codes/
I understand that most people use GraphQL over HTTP and that from a developer perspective you’d rather have HTTP status codes like every other REST API. To which I’d say, why don’t you just use REST instead?
There are a bunch of legitimate reasons why a clean separation of transport layer and application layer makes sense - you just aren’t using them so it feels like an arbitrary frustration to you.
Have you ever run an application like a golang REST API behind an envoy or nginx proxy or load balancer and gotten an HTTP status 500 back and wrongly assumed it was coming from your application/golang code, only to later find it was a problem at the proxy or load balancer? If so, you’ve experienced the misdirection of combining transport and application layer being forced to share a status field. This isn’t a trivial example - time is wasted every day by developers misdiagnosing errors originating from transport as application errors, and vice versa.
You might not like it, but separating them IS smart design.
Logs, logs, logs, you’ll pour over logs anyway. Hands up anyone who has run GraphQL over anything but http? Won’t be many. And then another show of hands please: who’s written a basic request using http tooling instead? Bet there’s tons!
They threw away loads of tooling for the sake of vanity imo
misdiagnosing errors originating from transport as application errors, and vice versa.
Shouldn’t the response body disambiguaite clearly whose fault it is? I mean you have to anyway if you advocate for ‘200 for everything’. You still have that same response body whether the HTTP status code is 200 or 500.
We honor the status code while providing an error body and it’s always blatantly obvious whether it’s an infrastructure issue or “true backend” issue when we see an issue. In my team I can’t recall anyone ever getting confused for even a little bit about whether an observed anomaly was web infrastructure or the backend, despite us setting HTTP status codes to error when, you know, we see an error.
Well no, the HTTP error codes are about the entire request, not just whether or not the actual header part was received and processed right.
Like HTTP 403, HTTP only has a basic form of authentication built in, anything else needs the server to handle it externally (e.g. via session cookies). It wouldn’t make sense to send “HTTP 200” in response to trying to access a resource without being logged in just because the request was well formed.
Many GraphQL and gRPC APIs do exactly that and return HTTP 200 even if the request didn’t auth.
Just because you are heavily biased toward using HTTP status for application layer errors doesn’t make it right. It is so wildly common that people can’t imagine it working another way, and I get that.
But it’s not “wrong” to do application layer auth status codes and apply no transport layer auth status codes It’s just a different paradigm than most devs are used to.
Ehh, that really feel like “But other people do it wrong too” to me, half the 4xx error codes are application layer errors for example (404 ain’t a transport layer error, neither is 403, 415, 422 or 451)
It also complicates actually processing the request as you’ve got to duplicate error handling between “request failed” and “request succeeded but actually failed”. My local cinema actually hits that error where their web frontend expects the backend to return errors, but the backend lies and says everything was successful, and then certain things break in the UI.
frontend expects the backend to return errors, but the backend lies and says everything was successful, and then certain things break in the UI
That’s a double failure then: not only does the backend do it wrong, the frontend devs don’t even know it. If they’d agreed on one way of handling it, they’d still be able to work it out. But if the devs don’t even communicate their standards with each other and the frontend devs obviously don’t know about the problem…
Yep, their frontend used a shared caller that would return the parsed JSON response if the request was successful, and error otherwise. And then the code that called it would use the returned object directly.
So I assume that most of the backend did actually surface error codes via the HTTP layer, it was just this one endpoint that didn’t (Which then broke the client side code when it tried to access non-existent properties of the response object), because otherwise basic testing would have caught it.
That’s also another reason to use the HTTP codes, by storing the error in the response body you now need extra code between the function doing the API call and the function handling a successful result, to examine the body to see if there was actually an error, all based on an ad-hoc per-endpoint format.
So I assume that most of the backend did actually surface error codes via the HTTP layer, it was just this one endpoint that didn’t
How is this getting even worse still? Why would a single endpoint work differently? That suggests they have standards, just one arsehole decided to shit on it and the rest didn’t vet their code enough to catch the issue.
otherwise basic testing would have caught it
I worked QA in a small dev team for two years. You might be surprised how uncomfortable you can make some developers within five minutes of “basic testing”. By the time I left, the team lead loved me as much as some of the devs must have hated me.
Think the point would be that it’s super easy to also set a ‘non-ok’ status in HTTP. Sure it may be insufficient for sophisticated handling, but at least you can get a vague sense of ‘something went wrong’…
Sure have your more specific API specific error code and your error details in the body, but at least toss a generic ‘500’ into the status code. I often find myself writing client software where I don’t need specific handling I just need to know ‘it failed’, and it’s obnoxious to deal with these interfaces where I have to sweat multiple potential ways for it to report failures when I just don’t care about the specifics. Sometimes an API doesn’t even have a consistent place that it sticks it’s return code, some don’t even define a reasonable way to know ‘failure’ and require you to explicitly map a huge number of ‘info’ to ascertain if it’s normal or error type state.
deleted by creator
Absolutely true, but Graph-QL has never pretended to be REST.
Another favorite is when the API barfs a stacktrace instead of valid JSON.
Every time I see someone recommend this at work I die a little inside. Like… C’mon!
I’d rather see this than actual rest or the more popular use the bits of rest that are convenient.
you’d rather have no responses following a standard rather than only some doing that? No, thanks.
Yes I’d rather have a self defined standard that accurately covers the scope of an application and it’s use cases than stretch an old standard design for basic hierarchical text docs to work for a modern application.
And what’s inherently new in modern applications? We’re transferring state and operating on resources just like we used to do. Most web apps are variations of CRUD.
Yes most things are crud if you zoom out enough that doesn’t mean REST is just fine. The scope is larger now, the states are more complex and interrelated, relationships are more complex, data privacy laws can affect the physical implementation. REST also has a lot of baggage that leads to excessive bike shedding, or refusal to allow useful endpoints that aren’t sufficiently restful. Proponents also tend to be more concerned with the purity of the api than the usability and effectiveness of it
refusal to allow useful endpoints that aren’t sufficiently restful
And there are good reasons for that, GraphQL-like endpoints seem great to use, but are often a bad idea. The more freedom is given through an API, the less guarantees one can deliver. Security, scalability, and maintainability all become more difficult for APIs with endpoints that attempt to do several things at once.
But most importantly, REST doesn’t tell you exactly how to build your endpoints, as long as they’re stateless, cacheable, and refer to system resources with enough context to allow their direct manipulation.
These are good principles for older and modern web apps, that hasn’t changed. In fact, one can argue that the larger and more complex the system the more important it is to simplify its endpoints. And you can build pretty complex systems while following these criteria.
Fully agree, purity of REST is dubious, but a ‘REST-as-possible’ absolutely is helpful to keep people from going way of the rails in ways that annoy external consumers of their API. One API I dealt with claimed to be ‘REST’ but basically everything you did was ‘Create a Task’, ‘Get Task’. No modeling of state other than the state of remote function calls, which might have been nice for them but now I have to lean what tasks are possible and how to create them when a more REST like hierarchy would have been a bit closer to ‘self documenting’.
This is why I’m not a fan of REST, the whole as possible part is meaningless. It could be an api that’s 99% REST with a few well thought out methods for common actions that aren’t quite REST, or it could be a mess of an api that uses PUT occasionally.
Self documenting at an application api level is not really possible. What I’d rather have is consistency and predictability, which is impossible in a REST as possible system.
Yes, there are certain things that don’t map to key principles of REST, and I have upon occasion see people way too hooked on purity of REST for any practical end.
However, to the extent that you at least consider how it could map, then that’s helpful.
If you say “you can’t have an application error, you must ONLY use HTTP error codes”, that would be bogus. But if your application knows it has an error, why not also set HTTP status code to indicate an error as well? You have to set a status code anyway, might as well at least get the first digit right, or just 500 == error, 200 ==OK if you don’t want to hash out 4XX v. 5XX.
REST may not be sufficient, but that doesn’t mean it’s helpful to actively work against the HTTP semantics when they could be a vague indicator consistent with your API.
There’s also value in treating http as just a transport later. It can give you clear boundaries, 200 the app processed the request, anything else the app didn’t process it.
But what is the value of a 200 OK when the request absolutely failed? As a caller, I don’t care that it successfully was conveyed but still utterly failed. Depending on my usage, I may only care about pass/ fail and the backend insisting I have to handle multiple different ways of expressing failure is just more work with no value.
Using 500 does nothing to preclude your application errors. If the caller wants nuance, it can still have it in the body or headers.
Right? REST is the transport, if you bend it to convey general/application errors it’s probably going to get bent out of shape eventually in a way that’s hard to clean up
The people that decide which rules are important or not when designing a “REST” api are generally insufferable as well.
