Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

API Practices If You Hate Your Customers

queue.acm.org

Post reply on HN
Print view View original

71–80 of 258 posts

Re: API Practices If You Hate Your Customers

#71

Post by wool_gather »

e9 wrote: post #52
Fradow wrote: 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…

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.

Re: API Practices If You Hate Your Customers

#72

Post by hnick »

gtsteve wrote: post #44
favorited wrote: post #28

Earlier quoted context omitted.

There's often a semantic difference between null and empty. Like, if I'm checking the result of a batch processing job, I want to know if the job finished & resulted in an empty set, or there is simply no result yet. It's "the thing you're looking for doesn't exist" vs. "the thing you're looking for exists, but is empty."

That's fair to say I guess - but it should be accompanied by some other property to indicate a condition like that. The API I'm thinking of though was effectively a wrapper around a database query which retrieved items. That's what gets me about that decision you see. When you get nothing from a database, you get an empty set. The runtime was some version of .NET Framework, which by default would write an empty set a…

Perl's DBI module gets around this with a value "zero but true" aka 0E0.

It is useful in cases such as indicating an operation was successful, but zero rows were affected. Using it as a number resolves to zero, using it as a boolean results in true.

I think in the general sense under API though, a status flag is the best way to avoid confusion as you say. Null could just as easily mean 'error' as 'not yet finished'.

Re: API Practices If You Hate Your Customers

#73

Post by blacksmith_tb »

shantly wrote: post #61
saagarjha wrote: post #41

Earlier quoted context omitted.

There's no need to shame people who are wrong.

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".

Ah, but that's the kinder, gentler version of "what's sauce for the goose is sauce for the gander"[1] which seems even more apropos.

1: https://en.wiktionary.org/wiki/what%27s_sauce_for_the_goose_...

Re: API Practices If You Hate Your Customers

#74

Post by ergothus »

dx87 wrote: post #34
tbirdz wrote: post #24

Earlier quoted context omitted.

I really don't like your story. The junior is clearly behaving immaturely and inappropriately by CCing others and not using an appropriate tone, but your response is to... retaliate by doing the exact same thing to him? What lesson is the junior supposed to learn here? That acting that way is A-OK as long as you have seniority and are factually correct? At least the junior has the "excuse" of being a junior, but real…

I'm not seeing anything wrong with what OP did. By CCing everyone, the junior is trying to make themselves look good by making OP look bad. The junior learned that if they act like an ass, especially an incorrect ass, the other employees won't tolerate it.

That's the DESIRE for what the junior learned. But is that what they actually learned? One could just as easily (or more easily) decide instead that this is the way business is done. It's literally all they've ever seen.

Re: API Practices If You Hate Your Customers

#75

Post by wool_gather »

paulddraper wrote: post #68
e9 wrote: 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…

For example, suppose you want to distinguish between a missing/deleted resource /myuser/23123 and a completely invalid query /muser/23123. Both of these are 404 (or 410 for permanent caching) responses according to HTTP, though they have very different reasons for "non-existance".

No, the "completely invalid query" is 400.

404 is only for "the request makes sense but that specific resource doesn't exist".

Re: API Practices If You Hate Your Customers

#76

Post by reificator »

Fradow wrote: 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…

IIRC cross domain requests are often one of the causes for this style of API design. I remember in older browsers at least anything not in 2XX would be unreadable by the client, so they had no idea what actually went wrong on the frontend.

Re: API Practices If You Hate Your Customers

#77

Post by jcims »

I’d like to add ‘Avoid any permission model for API keys’.

Even with multiple keys, if they are all god-mode it’s difficult for a central operations team to give internal users API access without risking unauthorized changes or audit findings in regulated environments.

Re: API Practices If You Hate Your Customers

#78

Post by [deleted] »

paulddraper wrote: post #68
e9 wrote: 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…

For example, suppose you want to distinguish between a missing/deleted resource /myuser/23123 and a completely invalid query /muser/23123. Both of these are 404 (or 410 for permanent caching) responses according to HTTP, though they have very different reasons for "non-existance".

[deleted]

Re: API Practices If You Hate Your Customers

#79

Post by ergothus »

akurtzhs wrote: post #5
gtsteve wrote: 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 .…

returning a null array to represent no items To be honest, that's what I'd expect. What do you dislike about that result, and what would you prefer to see returned? Jump straight to 404? returning a single object without an array to represent one item. So an array if there's multiple results, and a bare object for a single result? That's unpleasant.

> Jump straight to 404?

That's my pet peeve. I completely understand the logic - using the HTTP status code to show the result of interaction with the resource is very RESTful - but my complaint is that unless you provide more context, a 404 doesn't tell me if I'm getting a response of "that resource doesn't exist" vs "you're accessing a url pattern that will never work".

So if you want this random internet user to be pleased, never return a 404 response unless the caller is able to see this difference. (Usually having SOME form of body unique to the API is sufficient to prove the 404 is not because of a bad API call).

Giving me the HTML to your site 404 page when I called a non-HTML API is likewise sad-inducing.

Re: API Practices If You Hate Your Customers

#80

Post by hnick »

tomaszs wrote: post #26

Personally i think API should be obligatory. Every company should provide it with respect for private data. Additionaly if a company does not have it, it should be prohibited to block automatic measures to process the system and data. There should be a pricing model to cover basic expenses made by the API usage. Maybe you wonder why on earth it should be legally allowed to process automatically system data? We have a…

Does "every company" include the thousands of local businesses running Woocommerce or Shopify?

Larger companies love regulations like this because they can afford it, and it keeps smaller competitors from ever growing to be a threat.

I'm not saying they should be able to do whatever with data - but for such providers, manually replying to an email is preferable than implementing a complicated technical solution they can't understand (and will often likely mis-configure, exposing your data) when they just want to sell hats.

Post reply on HN