Why Developers Hate Your API

June 2, 2014

APIs are all the craze, but it's not all interfacing and nirvana. Developers sometimes hate your API, not for what is does but for what it doesn't do, doesn't offer or doesn't explain.


Like any good software, a good API sweats the details. At the recent Glue Conference in Broomfield, Colo., I had a chance to duck into the session "10 Reasons Why Developers Hate Your API (and what to do about it)" presented by John Musser, the founder of ProgrammableWeb, a recognized online resource on open APIs.


Musser has seen a fair share of social media that takes companies to task over terrible APIs and hopes his "10 Reasons..." will help people learn "how not to become that company." After all, an API that goes unused is not really an API at all. Musser's list also helps those adopting APIs to evaluate and predict the relative success they might enjoy if using that API. See Musser's list of reasons below spiced with a bit of his commentary:


No. 1: Your Documentation Sucks
Inaccuracies, dated, static, unloved. If those describe your API, you're in rough water. Fixes: Clearly state what your API does; clarity (think language localization); organization - "Often docs suck because I don't know where I am," says Musser; try interactive documentation such as provided by Swagger and I/O Docs and RAML.


No. 2: Your Communications Skills Need Work
You don't keep developers informed, you don't communicate changes, the code broke without warning, and where is support coming from are some of the angst developers have. Musser offers up six different fixes, including provide change logs, roadmaps, forums (think Stack Overflow) and email. "You can put a lot of great stuff in email. It is targeted. Developers love that," says Musser.


No. 3: You Don't Make it Easy
You don't provide "Hello World." Or a starting guide, you hide the keys, you forget the SDKs, and you don't provide cut and paste. Again, Musser has a range of fixes here: make it clear what the API does; quicken (or skip, initially) sign-up; offer wizards and free trials. "The big trend in the past 12-18 months is more API providers are using GitHub for sample code. Microsoft has OneNote development stuff up there," says Musser. 


No. 4: Lawyers
Lawyers are a fact of tech life, but they don't need to kill your mojo. Musser suggests reversing the vibe legal language throws out. Official legal disclaimers can be accompanied by an English translation. Provide an easy entry into the required legal stuff; shorter equals better, etc. Musser suggests sharing the wealth, "How am I going to make my API a win-win," he says.


No. 5: Your API is (slow, buggy and) unreliable
Things will go wrong, break or be taken down by an outage. Musser suggests a status page, a monitor and transparency. "If something happens, talk about it," he says.


No. 6: You don't give me the tools to help me succeed
Developers want to debug and test. They want to know their usage (and its cost). Solutions include a dashboard (i.e. Stripe), a log (i.e. Twilio), a sandbox (i.e. Twilio), a playground (i.e. Google), and a test console (i.e. Apigee).


No. 7: You're marketing to me, not helping me
Musser is succinct; "Developers hate marketing." He suggests listening as a key trait, and offering code and a phone number as alternatives to whitepapers and self-service support. Good fixes here include evangelists, events and hackathons.


No. 8: Your API is Too Complex
Don't customize (re: protocols and formats). "The more one off an API is, the higher the friction level, and the more likely it is that developers don't love your API," said Musser. Over engineering isn't your friend. Running with the herd appears to be a prudent idea. Use of REST is trumping SOAP, JavaScript and XML-RPC. JSON is used in nearly 70% of new APIs, while XML use has fallen below 20%.


No. 9: Be Pragmatic
Shorten the time it takes developers to get from landing on your API site to having some code working. "The higher the number, the more the drop off," says Musser. He calls this your TTFHW (Time To First Hello World). Suggestions, have a great developer experience, and use the "fixes" discussed in numbers 1-8. 


No. 10: You Haven't Learned (from the best)
Role models. "We have been doing this for a decade; consider the whole body of knowledge. It's good to know what good looks like," says Musser. Some of his suggestions: companies: TwilioStripeGitHubSendGrid; conferences: GlueAPIstrategyconference.comapidays.ioiloveapis2013.comapicon.programmableweb.com and apiconference.com.


Finally, Musser says to remember that a great API is a journey, not a destination. "It is ongoing."
Musser's presentation is available on Slideshare.