This article expressed a lot of what I’ve been mulling for years.
I must’ve spent hours of my life poring over the Wikipedia HTTP Response Codes page, looking for the most expressive error code for my situation. It’s barmy.
You don't need to. For me, REST can be as simple as: encode the type of request into the URL, request parameters into URL parameters and/or query parameters, request data into a JSON payload. Use GET for read-only operations, and if you're really not particular about it, use POST for everything else. Return 200 for success, 400 for client error and 500 for server error. Transport a more detailed application error code and description in the response body. That's it.
You don't even need that. I don't think there is anything wrong with returning a 200 response with a JSON body that has some 'error' tag built into it. It may not be purely RESTful, but if it's obvious to the developer interacting with the API, who cares.
Yep and when I have to investigate production issues, you're the guy that makes me do slow wildcard queries of the detailed error text instead of just filtering on the (indexed) response code. You push your laziness onto the rest of the world that way.
The worst one I worked with recently would return 200 and only a human readable error message (no status). On top of that the message is sometimes phrased differently. Here is an example from memory: "The field email is not valid." and "You provided an invalid username."
I disagree, at a minimum, use 200/400/500. Each grouping of error code defines semantics which are implemented by generic clients / servers / middle boxes / monitoring agents etc. These are things out of your control, and often ran by a range of different companies. Debugging these is .. hard.
That means I can't use any kind of generic retry / back off code because I've now got to start dealing with your custom errors, and if you have html versions of the info Google will start demoting you.
You're assuming you want your API to work with a specialized crawler, like Google-bot. If that's important, then sure, design your API so Google-bot can crawl it nicely, but then it's Google designing your API, not you.
I think you missed his primary point. By doing what you describe above, generic client side code to handle retries/backoff etc etc is rendered useless. Your users now have to implement something custom for this (and, if your doing network operations and DONT do this, you likely don't have a very robust system).
> You're assuming you want your API to work with a specialized crawler, like Google-bot.
Not really, I just don't
In general, the key point as about working in a generic way, given that it's so simple.
I don't like the idea of returning a human readable message that says there was an error but a machine readable message that says everything was fine. I have far too many cases of having to deal with human text explaining that a value is missing already in my data.
Not at all. Some languages and libraries don't handle non-200 status codes nicely, they may raise exceptions for each code, or maybe not. For example, Python's basic urllib library makes it easy to get 200 responses but a hassle to get anything else (you need to wrap it in a try/except).
For some APIs, it definitely does make sense to use proper status codes, but for others, it's like fitting square pegs into triangular holes.
well most consumers work better with 400 errors.
(i.e. angular1 or even angular2 where the 4xx error codes will be inside the error clause of the promise/observable)
I agree. There are plenty of freedoms built into the REST way that enable you to create more or less detailed responses.
"I don’t care. Trees are recognized by their own fruits.
What took me a few hours of coding and worked very robustly, with simple RPC, now takes weeks..."
Weeks? For a REST API? No, I don't think so. REST gives you the tools to be pragmatic and quick, so use them.