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

181–190 of 258 posts

Re: API Practices If You Hate Your Customers

#181

Post by eecc »

favorited wrote: post #28
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 .…

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

Ehm you shouldn’t GET for the result, but for the job descriptor. If you really need to GET the result then you should expect an HTTP 4xx or 3xx response.

There is no justification for NULLs

Re: API Practices If You Hate Your Customers

#182

Post by mrgriffin »

ergothus wrote: post #111
kelnos wrote: post #101

Earlier quoted context omitted.

Responding politely could also teach the junior that it's ok to act like an asshole, because he'll get a polite response no matter what. I suppose the ideal response would have been a polite correction, followed by a polite rebuke regarding the junior's tone and behavior, but I can't fault someone for responding to fire with fire on occasion.

A polite response does not have to be a meek response. You can be blunt, you can point out all the problems, while still being polite. That also has the advantage of being 100% clear. "You just told hundreds of people my code is poor. You attacked me, and my professional reputation, and you did it inaccurately. This gives me little reason to respect you or want to help you. Asking without copying the world and withou…

I've gotta say, if I was a third party to the exchange that involved your suggested message I would think the senior developer was a pompous and condescending ass. In the UK we (or at least I) wouldn't consider what you wrote to be a polite response.

Re: API Practices If You Hate Your Customers

#183

Post by jeltz »

save_ferris wrote: post #36
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…

> decided everything should return 200 Sounds like that decision came from someone who didn’t spend much of their career consuming APIs.

I spent a quite big part of my career consuming APIs and an API which always return 200 is no big deal. The opposite which I have also encountered is much worse, returning successes with 4XX, because some libraries do not like that. Why does the opposite happen? Because sometimes it is not obvious if something is an error or just another return value.

Re: API Practices If You Hate Your Customers

#184

Post by arethuza »

Moru wrote: post #175
arethuza wrote: post #165

Earlier quoted context omitted.

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

And since the boss knows you are right because of your previous behaviour, all you need to do is ask the boss to take care of the disturbing element if it continues.

That's making a lot of assumptions about your 'boss'.

Re: API Practices If You Hate Your Customers

#185

Post by irishsultan »

saagarjha wrote: post #12
akurtzhs wrote: post #5

Earlier quoted context omitted.

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.

> What do you dislike about that result, and what would you prefer to see returned? It’s inconsistent and means I need to write special case code to check for it, when before I could choose to. It should return an empty array.

null array sounds like it's an array (presumably an empty one), it would have been clearer if OP had said null instead.

Re: API Practices If You Hate Your Customers

#186

Post by rwmj »

Here are a few more:

* Aggressive rate limiting that makes it hard to use the API in real world situations. Especially if there is no documentation about what the limits are.

* Throwing errors with no explanation about what went wrong or how to correct it. Especially effective if given two very similar requests, one succeeds and the other one fails.

* Throwing errors randomly / when under load / when not under load / based on the phase of the moon.

* Having absolutely no example code anywhere in the documentation.

* Requiring hundreds of lines of code to even establish a connection to the API.

* Requiring a specific client library to access the API. Extra points if it's Windows only or requires a specific out of support version of Python 2.

Re: API Practices If You Hate Your Customers

#187

Post by nothrabannosir »

pirsquare wrote: post #85

I've worked with plenty of APIs (> 50). The biggest headaches I came across are bureaucratic stuffs rather than poor API designs. For example, there are vendors (like ConstantContact) that requires you to provide your credit card to get an account for API testing. You know what, they auto-bill your card after X number of days and require you to call them up to cancel your subscription. Because I'm on the other side o…

If you ever find yourself in that situation again: send them an email and explain you’ll contact your bank and issue a chargeback if they don’t cancel it without a phone call. The issue very quickly resolves itself; chargebacks are expensive.

The power is in your hands; use it. Don’t play their games.

Re: API Practices If You Hate Your Customers

#189

Post by 3xblah »

"Technique #5: Use a terrible protocol

Debugging is boring. Wouldn't you rather appeal to customers who write bug-free code on the first try?

To really show disdain for your customers, use a proprietary protocol so that language support is limited to the client libraries you provide, preferably as binary blobs that are never updated. If you design it carefully, a proprietary protocol can be difficult to understand and impossible to debug, too.

Alternatively, you can use SOAP (Simple Object Access Protocol). According to Wikipedia, SOAP "can be bloated and overly verbose, making it bandwidth-hungry and slow. It is also based on XML, making it expensive to parse and manipulate—especially on mobile or embedded clients" (https://en.wikipedia.org/wiki/SOAPjr). Sounds like a win-win!"

I remember when the early days of Amazon S3, trying to write Bourne shell scripts using shell built-ins and single purpose UNIX utilities to form the HTTP and interact with the servers, instead of scripting languages with libraries like Perl, Python, Ruby, etc. This is how I interact with HTTP servers normally. I never have any problems keeping things simple and dependency-free.

To do this with S3, it felt nigh impossible. There were small errors in their documentation of how things actually worked. It felt like they were intentional just to trip me up. I know they were not.

The official recommendation back in those early days of AWS was to use one of the protocol options provided by Amazon, HTTP or SOAP. You would think, heh, I will avoid SOAP and keep it simple. I will just use HTTP.

The truth is both required using scripting languages with libraries. Amazon's own utilities were written in Java. I know developers have their reasons for making these choices, but as a user, that complexity really put me off.

From my perspective, this ACM article is right on point.

"When I see a top-down description of a system or language that has infinite libraries described by layers and layers, all I just see is a morass. I can't get a feel for it. I can't understand how the pieces fit; I can't understand something presented to me that's very complex. Maybe I do what I do because if I built anything more complicated, I couldn't understand it. I really must break it down into little pieces." - Ken Thompson http://genius.cat-v.org/ken-thompson/interviews/unix-and-bey...

Re: API Practices If You Hate Your Customers

#190

Post by swiley »

3xblah wrote: post #189

"Technique #5: Use a terrible protocol Debugging is boring. Wouldn't you rather appeal to customers who write bug-free code on the first try? To really show disdain for your customers, use a proprietary protocol so that language support is limited to the client libraries you provide, preferably as binary blobs that are never updated. If you design it carefully, a proprietary protocol can be difficult to understand an…

Some proprietary protocols are easier to implement than open ones. The other day I wrote against one API server that just accepts messages in json format over an ssl socket. It was maybe 3 or 4 lines of python? (Not counting setting up the connection) and probably wouldn’t have been bad in C. For the shell you could use OpenSSL s_connect and something to generate json (awk or echo would probably be enough since it was all flat dictionaries of strings.)

> There were small errors in their documentation of how things actually worked.

that sucks, but I’ve run into that with people speaking “http” and not just special protocols.

Post reply on HN