Live data from Hacker News

API Practices If You Hate Your Customers

queue.acm.org

161–170 of 258 posts

Re: API Practices If You Hate Your Customers

#161
post #2

I was expecting to see two of my pet hates - returning a null array to represent no items, and returning a single object without an array to represent one item. I also once worked with an API where you had to send the data in POST format - abc=123&def=456. After much pressure from their customers, they finally relented and added an XML version of their API... where your request could look like this: abc=123&def=456 .…

For those Gophers reading this and sobbing silently, there may be hope: https://github.com/golang/go/issues/27589

Why would you want to marshal a nil slice to json as non-null? That just hides the fact that you had a nil slice. In fact, that's the exact opposite problem; representing nulls as empty arrays.

Re: API Practices If You Hate Your Customers

#162
post #52

Earlier quoted context omitted.

It depends. I've seen bigco use this technique and their reason was that they wanted to separate problems with API and request from actual issue with their servers/platform. So if you get 200 it means they received request successfully but if there is issue with request they'll include error in response with 200. If it's anything else then there is a networking or delivery problem. It's not standard way to handle thi…

This is what the 400 and 500 ranges of HTTP status codes are for. The former when the problem is on the client side, the latter for a problem on the server. And you can still send a descriptive body for the error, if you so choose.

This is not true. Counterpoint, responses like 404 or 503 Bad Gateway do not come from the destination server. They do not indicate the intended server received your request.

Re: API Practices If You Hate Your Customers

#163
post #148

Earlier quoted context omitted.

404 indicates an error, if the result is just empty but not erroneous 204 "no content" may be better.

+1, 204 is underutilized for no-result cases.

In the browser it will also do no page refresh as there is nothing to render.

Re: API Practices If You Hate Your Customers

#164
post #32

I was totally expecting to see something about using a protocol in an unexpected way, because "the protocol is not good enough". I had to work with an API where the company decided everything should return http code 200 (well, at least all 4XX errors), and give the error code in the JSON response, mixing existing 4XX errors and their own errors. When pointed out, the support answer was "we chose to give meaningful er…

>I had to work with an API where the company decided everything should return http code 200 (well, at least all 4XX errors), and give the error code in the JSON response, mixing existing 4XX errors and their own errors.

So here's the deal with this pattern...If you're returning a typed error response, something the client application should interpret, you want to be able to know which error responses will actually have that body and will not be a generic error like a 404 or a 503. If the response code is 200, you can be generally sure that the response came from the target host. Thus, the client knows they can parse an api level error from a 200 response and they should not attempt to parse non-2XX responses. I don't love the pattern but its not completely pointless.

Does anyone know if the HTTP spec guarantees codes in 4XX range should only come from the intended host? It seems like 400 is a safe bet but I've never double checked myself.

Re: API Practices If You Hate Your Customers

#165
post #61

Earlier quoted context omitted.

If they're trying to shame or chastise others, while being wrong, seems fair to me. Then again, I subscribe to the "play stupid games, win stupid prizes" school of dickish behavior correction. Or, to defer to the ever-wise Gods of the Copybook Headings: "What's good for the goose is good for the gander".

I've noticed that if you stay strictly professional, folks think higher of you and they feel shame for having done this. You also appear way wiser and likeable - all of which gives you more clout. And if you're more often right than your peers, everyone benefits by your having more clout. I've been in this situation before and I've found this approach beneficial.

"I've noticed that if you stay strictly professional, folks think higher of you and they feel shame for having done this."

Some do, some think it is a sign of weakness and start behaving even more unreasonably.

Re: API Practices If You Hate Your Customers

#166

Earlier quoted context omitted.

> When pointed out, the support answer was "we chose to give meaningful error messages instead of HTTP codes, that's why we respond with 200 in case there's an error in the request". Not the answer I was expecting. I don't see the problem here. As a developer I'd much rather receive a standard json packet with information helping me figure out what went wrong. I really don't understand your complaint here, I've desig…

Totally agree that specific messaging is very convenient, but meaningful error messages and meaningful status codes aren't even remotely mutually exclusive. It's perfectly legitimate and even easy to send a 4xx or 5xx with a response body as JSON (or, for bonus points, with any other content type the client requests from possible server capabilities). And in my experience, having an out-of-body/band general indicator…

>but meaningful error messages and meaningful status codes aren't even remotely mutually exclusive

They actually are. Things besides your app code can response with 404 and 503 but not your error body. 4XX and 5XX bodies must be parsed more carefully and cannot be assumed to have a consistent structure with the same level of trust a 200 response would.

Http codes are nice but it makes api error parsing much more complex so there are some trade offs.

Re: API Practices If You Hate Your Customers

#167

Earlier quoted context omitted.

Normally that would be true. But it's necessary to shame people who work the trade desks, or else they will never learn.

I honestly think people learn better if you don't shame them.

I honestly think it depends on the entire context including the people and all this generalization is useless and a waste of precious Internet bits.

Re: API Practices If You Hate Your Customers

#168
post #2

I was expecting to see two of my pet hates - returning a null array to represent no items, and returning a single object without an array to represent one item. I also once worked with an API where you had to send the data in POST format - abc=123&def=456. After much pressure from their customers, they finally relented and added an XML version of their API... where your request could look like this: abc=123&def=456 .…

I had this happen with a vendor that was told that they needed to add REST support to their legacy Java app. They turned up with an API that encoded XML as base64 and put that in a POST variable on HTML page. Then they added their own crypto on top with hard-coded RSA keys. They helpfully included both the public and private keys in their documentation. When they turned up for a meeting to present the fruits of their…

Unfortunately I have vivid memories of one API I worked with (many years ago) that included entire encoded XML documents as attribute values within top level XML. At least there was only one level of recursion.

Still, perhaps not as bad as using XML documents as database keys...

Re: API Practices If You Hate Your Customers

#169

Earlier quoted context omitted.

Two reasons why using 200 instead of 404 can make sense: - No way to distinguish between the api client calling the wrong URL eg /mytypo/12345 instead of /myquery/12345. With 404, the client will not realise their mistake without debugging. - Lots of 404 errors can trigger security sensors. Having to whitelist 404 in a security sensor can be a pain to convince the team that manages them. Doubly so if they are part of…

With a 200 your client won't know they've done anything wrong without debugging either. There is nothing preventing you from returning a detailed error message with your 404.

If under your suggestion you have to look at the details of a 404 anyway to get a detailed error message, what is the point of the 404? Your client always has to do an explicit check for error/no-error. Why make them check two different locations? Just always look at the body: one location.

Re: API Practices If You Hate Your Customers

#170

Earlier quoted context omitted.

While we're asking questions: what stack out there makes reading/writing HTTP headers hard? Because that's all it takes to work with response codes. And yes, of course parsing JSON isn't difficult. Note that I said parsing messages -- the message field not the response body. And parsing that message field and checking conditionals to determine your client's behavior is something you'll have to write code for unless y…

Two reasons why using 200 instead of 404 can make sense: - No way to distinguish between the api client calling the wrong URL eg /mytypo/12345 instead of /myquery/12345. With 404, the client will not realise their mistake without debugging. - Lots of 404 errors can trigger security sensors. Having to whitelist 404 in a security sensor can be a pain to convince the team that manages them. Doubly so if they are part of…

> -No way to distinguish between the api client calling the wrong URL eg /mytypo/12345 instead of /myquery/12345.

More often than not, this distinction matters less than one might think. In either case, you've got an upstream problem for the client: how it's determining the `mytypo` portion of the path or how it's fetching invalid identifiers. This is actually part of the point of the philosophy behind REST.

But if caring about fine distinctions is the point here, there's no appreciable improvement between using 404 for both "something's bad about the path" and "path's good, no resource here" and using 200 for both "path's good, no resource here" and "everything's fine!" Especially when, personally, I think the distinction between "I got back data!" and "I didn't get back data" is more important than "I didn't get back data for reason X" vs "I didn't get back data for reason Y."

Now, maybe you don't agree with that prioritization, or maybe you'd argue "Oh, I just handle did-vs-didn't-get-data situations both under 200 with a message somewhere in the response body." Cool. As my earlier comment points out, you can do that in the response body of a 404 too.

So of course it is quite possible to make distinctions between why a 404 error code happens, just the same as it is for what kind of 200 you're getting back.

And you can still go straight status header on top of that too: make your own 4xx for "resource not found even though URL is correct", maybe something like 434. Or if you're queasy about that sort of improvisation, use 400 with a status message in the body about an invalid id. Or if you're absolutely sure for some reason that it should be 2xx, consider 204 (though it sure seems like a bad id is a form of client error).

> Lots of 404 errors can trigger security sensors. Having to whitelist 404 in a security sensor can be a pain to convince the team that manages them.

I might well have a side-eye for a security team that sets its thresholds here too aggressively, but OTOH, a client that is generating a lot of 404 errors on legit URLs is either broken or it's getting fed bad ids by the API... or it is in fact malicious. In each case eyebrows should be raised. Hopefully any security layer is also sending back a useful status code and response body to the client.

> Aside from slightly less code to write, what benefit does 404 bring?

Like I said in my earlier comment, out-of-band broad status code can let you switch between error handling pathways well before you've spent time parsing a more detailed message in the body (which you may or may not get, depending on the error condition!), or even for specific error messages you have never thought of much less seen. Knowing what kind of error you're dealing with before you know the deep specifics is really useful across a variety of software situations.

And there's so much web tech and tooling that's set up to see 200 as "Everything is Fine, You Got What You Wanted!" You're working against the related infrastructure when you use 200 to indicate an error condition. You're working with it when you use HTTP status codes.

Post reply on HN