Now there’s this thing called REST that we all commonly understand and debate over. And I have run into so many issues that I basically abandoned calling it REST and now just call it an API.
And somehow it still all works just as well :)
You can delete the rest of the spec and clients can connect without head-aches but only if you can put up with the fanatics in your team trying to trace every bug to not following rest, in the rare case giving you no options other than trying patch after patch to make everything rest-compliant.
As long as HTTP is concerned (which must not be specifically REST), HEAD needs to be supported next to GET, too.
*except when the query string is too big, then use POST
REST is now in practice an API using JSON over HTTP with appropriate verbs. And it's 'stateless' in that the server doesn't have to track the clients prior requests to understand the current request. That's about it I think....
Does anyone think that's stupid?
Agreed that everyone ignores the HATEOAS clause of REST, even when they call things "RESTful", but that's because the HATEOAS clause is tremendously stupid. I don't know why it's so common for narrow-minded intellectuals to decide that the reason the world is so complicated is because nobody has sat down yet and decided to make it simple. No, the world is complicated because reality has a surprising amount of detail [1][2]. When one person (or worse, a committee) sits down and decides "this is the way all of the world's information will be organized from now on" (HATEOAS, the "semantic web", etc.) they envision automated tools that can browse information the way Web Browsers browse the web. But as complicated as HTTP, HTML, CSS, JS, CORS, SVG, and now WebAssembly are, they are dozens of orders of magnitude simpler than "all the information anyone might ever want to make available over an API". Writing hypertext that can be understood by a tool to digest how your API should be consumed is just not possible. It doesn't work for people who are new to the API (they need to read the docs no matter what), and it's useless overhead for the people who use the API all the time (the hypertext is delivered with every request!?)
People don't use HATEOAS because HATEOAS is stupid.
[1] http://johnsalvatier.org/blog/2017/reality-has-a-surprising-...
I have personally gone off the deep end and started writing 200, 400, and 500 for all my status codes instead of the specific 2xx, 4xx, 5xx ones.
If details of an error response need to be mentioned, it will be in the error response body.
My motivation came from GraphQL as it responds everything with 200s, and so far it has been humming along fine.
True REST are more guidelines if anything.
This is slightly annoying though, as other consumers (like `fetch` in JavaScript world for example) behaves differently if there is a error. If every status is 200, suddenly you need to manually check the response inside the returned promise, while if you answer with a correct status code when the server encountered an error (5xx), then it'll jump to the `.catch` part of the promise chain instead, which you're probably already handling anyways.
Similarly with curl if I'm not mistaken (don't have it in front of me). A 2xx would make the process return 0, while a 5xx would make it return non-0, so you can handle errors without having to read the actual response.
I can't believe the people here saying "fuck it, I always return 200"
Similar with curl, 502 returns non-zero, 302 not. 4xx IIRC as well zero unless --fail is in use. The default makes it sensible/useful for smoke tests.
Perhaps GraphQL was aware of such client side "bugs" it choose to go "OK" first of all.
For example, if you're rate limited (429), a robust API will still give you back data on how many requests you've made and how many requests you're allowed to make, so you're still going to have to check the payload regardless.
The combination of specific error status codes along with error messages has been redundant in my experience.
Furthermore, in Axios, checking for `error.response.data` isn't terribly far from `error.response.status`, so I'm unsure of this "worst client experience" you're talking about.
It's pretty intuitive for me.
I think its objectively worse that I, as the engineer, need to handle all of them differently when they all could have returned to me 429 instead and I could write a general wrapper for that.
how is
if error.response.status === 429 // then do something
different than
if error.response.data.err === 'RATE_LIMITED' // then do something
Also, do you mean to tell me that you've never had to elaborate on your error messages and just sent back status codes with no body?
I'm sorry but that does not sound like a robust API to me.
90% of my error responses have specified data, and I have to check the response body extremely often regardless of the status code being sent back.
If there's a way where we could say "this specific key will be this specific value in order to mean this specific scenario", I'd support that! But. Then. Isn't that the status that's I'm talking about?
I never said the error message can't or shouldn't be introspected and totally agree we should send our clients as much info as we can to make it clear on what they can do to fix any errors!
I just really really like being able to say "this specific field tells you, across all apis, what happened with this request" and don't see the gain in pushing that data into good luck finding out what key.
I'm currently dealing with an endpoint where it sends anywhere from 2-4mb worth of JSON data. Do I expect my clients to traverse every key and every deeply nested field to find what they're expecting for?
Absolutely not. because there's an internally standardized way of dealing with things and that is also precisely how we also deal with errors.
Now if you have an external API that faces many clients that you don't know about, then maybe there is consideration for usage of specific status codes.
But even then, your api should have documentation for it.
object graphs should be just called json or response body; you shouldn't use all these unorthodox terms.
a failure will be caught if a 400 was sent. This is how axios works - if you try a request, a 400 will automatically hit the catch.
a better designed system would be specificity. 75-90% of the time you're most likely going to look at the error body anyways.
I mean no personal offense but this is one of the most baffling and/or ignorant responses one could have imagined in this case.
json data => python server => redis
- json data gets serialized from json to string in the python server
- python server then stores that string in redis
to request from python server
- string is retrieved from redis server
- string is deserialized to send response as json
the Web client is in Javascript
JSON is native to Javascript
it is already readable to the client, there is no deserializing that needs to happen.
We have a standardized way of dealing with errors in which we will send 400/500
and have an error.data.err and an error.data.message in which err will give a title of the error, and the message elaborating the error in all of our errors across our APIs
the reason being is we don't need our developers to memorize dozens of generic status codes, and can be extremely specific in our error.data.err in which status codes can't.
It has worked for Facebook, It will work for us.
- It's non-standard, so different implementations will result in different formats