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.<p>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: <request>abc=123&def=456</request>.<p>Even better, note the & is not an &amp; - you can't even use a standard XML parser to interpret the result.<p>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.
I was totally expecting to see something about using a protocol in an unexpected way, because "the protocol is not good enough".<p>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.<p>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.<p>Another annoying practice is to answer 2XX, put the request in a queue, and not provide ANY information about the queue, which can be minutes or even HOURS long. Debugging is a nightmare. The one I worked with who did that did not even have the excuse of being a startup or small company.
I'm missing a few in the list:
1) Have an API but only expose that via some weird-ass tool instead of a normal protocol.
2) Have a lot of documentation but make it so bad it's useless (looking at Telebib2 right now)
3) Only return generic errors which are always the same
4) Refer to standards so you don't have to document them, but then deviate slightly so all standard tools don't work
5) Make it ambiguous (best one I've seen so far: 30% of the required fields must be filled in, doesn't matter which 30%).<p>I could go on looking back the projects I've done.
>"APIs also permit customers to use a lot more of your product. If they have to click, click, click to use your product, they're going to use it only a little. If an API exists, they can automate their use of your product, which would let them use it a lot more. They could automate provisioning for their entire company. They could build entire new applications based on your API. Just think how much more of your product they would be able to consume with an API."<p>This so much. One of our main adtech vendor is lagging behind on the API front. We've been chasing them for a while on when they'll be up to date so that we can build on top and they get back to us on how their other customers don't really want an API.<p>Of course, no one (beyond us tech crowd) goes to bed thinking oh I need an API to interface with my DSP.
But I'm sure they'd be delighted about what the API can enable them to do.<p>Here's an advice if you are building / improving a pretty consequent SAAS product :
Your UX sucks. Not that it is awful but it is likely not optimised for what your customers are doing, simply because you keep adding features and now it's bloated.<p>And I don't mean that it is an awful thing, it is the nature of such product to keep growing, because marketing, justifying salaries and obviously adding value.<p>Chances are, 80% of your customers are only using a good 20% of the features you offered and they'd rather have something that is tailored for efficiency to address their main pain point. So either you step up your game to offer that flexibility or you get your API game up to speed. Your competition might beat you to it and I know which product I'll choose.
#DJI<p>Re: <i>hiding docs</i>:<p><i>Luckily, this can be easily done by putting the documentation behind a login screen...</i>
<i>consider making your documentation a PDF file...</i><p>DJI's release notes for the DJI-SDK are only available for DJI registered developers. As a zipfile - of a single pdf doc.
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 of the world, I've to drop them a call in the middle of the night just to cancel billing.
Here's one from a vendor I currently integrate with - have multiple APIs (in this case, a SOAP one, a REST one returning JSON, and then some language SDKs that wrap the latter for convenience), and have their feature sets be an interesting Venn diagram with various intersections but no unions. Just today I found out that the in the extensive integration we've written using the SDK (which wraps the REST API, remember), I will have to shell out and use SOAP because one (1) parameter on one (1) object in their extensive object hierarchy isn't supported by REST or the SDK, just by the SOAP protocol. Nice.
Here are a few more:<p>* 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.<p>* 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.<p>* Throwing errors randomly / when under load / when not under load / based on the phase of the moon.<p>* Having absolutely no example code anywhere in the documentation.<p>* Requiring hundreds of lines of code to even establish a connection to the API.<p>* 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.
Use of multiple different sets of allowed characters in identifiers for entities in your API is also a good way to show you customers that you hate them..<p>Extra bonus points for intermittently using case-insensitive but case-preserving identifiers.<p>Microsoft Azure storage APIs is a prime example of this with 4-5 different sets of identifier restrictions dependening on what you're naming.
(Including one that allows any valid C# identifier, for which the documentation conveniently refers to the ECMA specification of C#).<p>Also enabling some special characters like # when creating entities, while knowing that # will be interpreted differently when fetching entities. Such that entities with # in the key cannot be fetched or deleted, but only created.<p>Extra extra, bonus points for retaining # support in the interest of backwards compatibility :)
My favorite was an API for a product you've heard of that couldn't be bothered to do datetime math correctly.<p>Their recommended solution: Make sure all of your intervals overlap by several minutes to avoid any problems. :-P
I’d like to add ‘Avoid any permission model for API keys’.<p>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.
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.<p>There should be a pricing model to cover basic expenses made by the API usage.<p>Maybe you wonder why on earth it should be legally allowed to process automatically system data?<p>We have a lots of great services online. But we can not move further, integrate them into even better ones, because of lack of APIs and bot bans.<p>Without it, we wont be able to create high level services people expect. And currently if these will be provided, than only by companies that have Monopoly over vast parts of online offering. Because they can make more monopolistic deals with service providers.<p>Another problem is that service owners have adventage over users. Because they can process users data to drive business decisions torwards them. But users can not process thr same data for their adventage. With more and more complicated systems user ends up being dependant on the company service and has no possibility of validation.<p>And this means even more trouble than we have today. So ye, open programmatic access as a human right.
I really liked Strip's API version scheme and how well done it is.<p>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.<p>WTF?
> Technique #8: Ignore the IaC revolution<p>Google Firebase has no API for creating projects. Therefore it is impossible to use Terraform or other IaC (Infrastructure as Code) tool to provision backends that send push notifications to Android apps. Manual steps are required. In this way, Google Cloud prevents its customers from using SRE best-practices.<p><a href="https://github.com/terraform-providers/terraform-provider-google/issues/2973#issuecomment-468180542" rel="nofollow">https://github.com/terraform-providers/terraform-provider-go...</a><p>Google as an organization is simply unable to focus on users.
I only ever use internal APIs at work. I've never used anyone's external APIs and am wondering if there's a whole tech ecosystem I'm missing out on. What are some commercial use cases you all have had?
I 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.
This article is junk. There are many reasons for not offering an API to customers.<p>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.<p>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.<p>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).<p>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.<p>The better suggestion is to analyze your business and decide if offering an API furthers your businesses’ goals.
A seemingly common one in the move fast and break things world is to provide all information in the form of hello world tutorials and youtube videos. The source code is its own reference, amirite?
This seems to be written from the point of view that the "industry" is all enterprise SaaS software or something. I don't think I'd agree with calling any of these "industry best practices". Maybe "commercial business software best practices". #2, 3, and 4 aren't really applicable to a ton of software products. There's a lot of niche software that isn't intended for the general public.
Question: do you guys find a graphql-only API acceptable in 2019? For us to develop a (good) REST API layer on top of our existing solution is a non-trivial piece of work, and GQL offers us all we need on the front end. Customers seem ok with it, but we haven't got any large enterprises yet.
Ha! Anybody who implemented a payment processor on their side of the fence to interact with Visa/Mastercard on the other side will have seizures while reading this article. Those API's are definitely written with "hate your customer" practices in mind.
I used to work in a company like that almost all techniques described in the article were in use.<p>Turns out it doesn’t piss only customers but developers (of the API) as well.
The API that was dragged out of my company's software team ticks oh so many of these boxes...<p>It's eerie, almost as if the author tried to use our system and then decided to write this...
Interestingly, many of Amazon AWS's apis don't break these rules, and I don't really hate them.<p>Charges for use. Manual documentation. Idempotency. A weirdo protocol.
I guess that explains why the ACM Digital Library doesn't have an API.<p>Even worse, they seem to forbid any sort of programmatic access in their ToS.
"Technique #5: Use a terrible protocol<p>Debugging is boring. Wouldn't you rather appeal to customers who write bug-free code on the first try?<p>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.<p>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" (<a href="https://en.wikipedia.org/wiki/SOAPjr" rel="nofollow">https://en.wikipedia.org/wiki/SOAPjr</a>). Sounds like a win-win!"<p>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.<p>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.<p>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.<p>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.<p>From my perspective, this ACM article is right on point.<p>"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
<a href="http://genius.cat-v.org/ken-thompson/interviews/unix-and-beyond" rel="nofollow">http://genius.cat-v.org/ken-thompson/interviews/unix-and-bey...</a>
A 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.
> An operation is idempotent if performing it multiple times yields the same result as performing it exactly once.<p>And then he casually offers an API that does different things on first and second call as the "good" example. If you have a "create a virtual machine" API it better create a fucking virtual machine. If I call the damn thing twice, I expect to have two VMs. If there is some sort of unique argument like create a named VM, I would expect API to throw an error if the name is already taken, no to just return like everything is normal.<p>And this guy is being all snarky about API design?