My favorite was an API for a product you've heard of that couldn't be bothered to do datetime math correctly.
Their recommended solution: Make sure all of your intervals overlap by several minutes to avoid any problems. :-P
API Practices If You Hate Your Customers
11–20 of 258 posts
Re: API Practices If You Hate Your Customers
#12I 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.
> 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.
Re: API Practices If You Hate Your Customers
#13This article really made me think about the Google Ads API. Miserable to work with.
Re: API Practices If You Hate Your Customers
#14I 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.
Presumably they would prefer an array always be returned. If zero items, an empty array; if one item, an array of length one; if more items, a longer array.
Re: API Practices If You Hate Your Customers
#15I 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.
[deleted]
Re: API Practices If You Hate Your Customers
#16I 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 .…
What would you suggest instead of an empty array for a 0 item return?
If you return an empty array, I can always process the result by looping through the array.
If it's sometimes an array and sometimes null, I need branched logic for each call.
Re: API Practices If You Hate Your Customers
#17Earlier quoted context omitted.
What would you suggest instead of an empty array for a 0 item return?
The person you replied to doesn't like returning "null". He/she would probably prefer returning an array that contains 0 items.
This makes sense now. If I did a GET to posts and got a "null", I would think I made some kind of error. If I get an empty array, I would (correctly) assume there are no posts yet.
Basically, GET to posts would always return an array of posts. Whether there are 0 (empty array), 1 (just one object in the array), or many (array with n length). This makes API logic way easier to handle without having to check what structure I received even with a 200 status code
Re: API Practices If You Hate Your Customers
#18I 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, and returning a single object without an array to represent one item.
This just reminded me of a long ago incident at a former employer. I worked in back-office at a hedge fund and was responsible for maintaining several APIs & services written in C++. The APIs were pretty straight forward query for object(s), get back a vector of objects. If nothing was found, you'd get back an empty vector.
The company also had a program where they'd hire grad students right out of school and immerse them in the trading desk, working on trading algorithms and such. One such kid sent in a "bug report" directly to me, CCing all of front office. The "bug"? We was querying for something that didn't exist, so he got back an empty vector. He didn't check that it wasn't empty, and immediately accessed the front of the vector. Boom, segfault.
Normally, I would have been kind to such a junior dev, but their original email was very condescending and went to an unnecessarily large audience - like hundreds of people that didn't have time for this. His email read something to the effect of "Your API is crashing my code. Fix your API."
Instead, this junior got a whole other lesson instead. I replied all, and included all of back-office on the email (so the rest of the team was aware to watch out for this clown). "The API is working perfectly fine and as designed. The fuck up is on your end. You queried for something that doesn't exist and proceeded to dereference and empty vector. Fix YOUR fucking code."
Re: API Practices If You Hate Your Customers
#19I thought the chosen example for idempotent requests was a bit funny as I don't think POST is necessarily idempotent and depending on your specific use case making it so may or may not be easy.
Re: API Practices If You Hate Your Customers
#20This article is junk. There are many reasons for not offering an API to customers. I run a small b2b app between two completely non-technical businesses. There is absolutely no need for me to have an API available to them, they’ve never asked for it and have no desire or ability to consume it. Believe it or not, there is also an expense to offering an API! An API is a product offering like anything else, and products…
I would argue the primary benefit of having an API even if not made public is that it will encourage better architecture , design, and development making the product more maintainable over the long run.
It also means you can scale if you ever do need to add a customer that wants to make use of an API.
Saying not to do an API because customers don't want it is similar to not using source control because you're the only developer.