API Practices If You Hate Your Customers
queue.acm.org
API Practices If You Hate Your Customers
1–10 of 258 posts
Re: API Practices If You Hate Your Customers
#2I 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.
Even better, note the & is not an & - you can't even use a standard XML parser to interpret the result.
Also: APIs that have a mix of strongly and eventually consistent calls and no documentation about which is which. Or, an API that was at one point strongly consistent turns eventually consistent without warning.
Re: API Practices If You Hate Your Customers
#3This 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 need customer support. API products need advanced support because they are technical in nature, you can’t use a call center for this type of support.
And I don’t really want random joes signing up for my API and doing god-knows-what with it. I’d much rather create a relationship with you so I know what you’re trying to do (so you don’t bring down my servers in the middle of the night or run up a huge bill because you’re use case is a little beyond what I can support).
The other points can just be summarized as “have a perfect API and perfect docs”. Ok. Thanks. Can you show me an example of this in the wild? Didn’t think so.
The better suggestion is to analyze your business and decide if offering an API furthers your businesses’ goals.
Re: API Practices If You Hate Your Customers
#4A pretty bogus article. If you can charge for an API and people are paying for it, why would you not charge for it? If people aren't paying then think about making it free and making it a doorway into your general product.
Re: API Practices If You Hate Your Customers
#5I 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.
Re: API Practices If You Hate Your Customers
#6I really liked Strip's API version scheme and how well done it is.
Recently I'm writing code that interacts with API of a Enterprise Product (fairly new, less then 3 years old) and its driving me crazy. They version every single API endpoints separately. So endpoint A to create a user is at version 7 but endpoint B to assign a group to a user is at version 4.
WTF?
Re: API Practices If You Hate Your Customers
#7I 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?
Re: API Practices If You Hate Your Customers
#8This 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 didn't downvote you but I do strongly disagree with pretty much everything you've said.
> 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.
Whenever I've used "small b2b apps," especially between non-technical businesses, if you don't have it I'm not asking for it. I know how hard it is to be a solo founder or part of a very small team so I'm either going to use your product as-is, or I'm not going to use it.
> API[s]...need customer support
There are plenty of small, niche APIs where there is out-dated documentation and not much else. I'm saying that's a great experience, but let's not pretend it's illegal to have an API without on-demand live support.
> And I don’t really want random joes signing up for my API...
The reasons listed here can all be handled via code. There are very few reasons to prevent automated sign-ups.
> The better suggestion is to analyze your business and decide if offering an API furthers your businesses’ goals.
If you think it can't, you're just not being creative enough. Every single API with more than 2 users is being used in ways its designers hadn't originally thought of. Many brains are better than one brain and you can often get more (and better) ideas from what other people are doing with your tech than you ever could on your own.
Re: API Practices If You Hate Your Customers
#9I 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?
The person you replied to doesn't like returning "null". He/she would probably prefer returning an array that contains 0 items.
Re: API Practices If You Hate Your Customers
#10A pretty bogus article. If you can charge for an API and people are paying for it, why would you not charge for it? If people aren't paying then think about making it free and making it a doorway into your general product.
I don't think they were arguing not to charge, I think they were arguing a) not to charge an obscene amount, and b) not to charge individually for every little thing someone might like to do (e.g. have a couple tiers but not full-blown a la carte pricing).