10 Reasons Why Developers Hate Your API

John Musser, founder of ProgrammableWeb, and now founder of API Science, is the first one to tell you that APIs are often not truly great. Yesterday at Gluecon, he told a packed breakout session how they can avoid that fate. He unveiled a new talk that describes the most common mistakes API providers make in his view, and what the fixes are to ensure that those mistakes aren’t made again. He covered such issues as bad developer experience, poor/inconsistent API design, and unreliable services. His objective, he said, was for attendees “to leave knowing how to get developers to love your API, not hate it.”

So, here are Musser’s reasons/problems, and the ways to fix them:
 #1 Your Documentation sucks. Let’s face it, you probably are not that one-in-a-million product that’s so good, it doesn’t need quality documentation. How to fix: explain your “big picture” to people, and focus on clarity, findability, and using LiveDocs solutions such as Swagger, I/O docs or RAML.
#2 Your communication skills need work and you don’t keep your developers informed. There’s another language you need to be skilled in: it’s called English. How to fix: use a change log, have a roadmap, release notes, a blog (see the AWS blog), a forum (check out SoundCloud as an example), and use email (like Twilio).
#3 You don’t make it easy. There are so many ways to simplify – why fight it? How to fix: explain what you do, make signup fast (see Stripe), “The 1-2-3” (see Constant Contact - they help you market), use quickstarts (see Twilio’s quickstart tutorials), do “free” and do “trial” (30 days for either), have copious SDKs (like MailChimp), and use GitHub (see OneNoteDev).
#4 One word: Lawyers. Things get miserable if the legalese gets out of control. How to fix: be clear by using simple and brief language, set the tone (see how the Etsy terms of use page explains their philosophy), shorter = better (see the single page used for the Google Developers terms of service versus PayPal’s 23 pages), think long term because developers invest a lot of time with you (see YouTube terms), and share the wealth. “You want people to build in your Platform and be your partner.”
#5 Your API is unreliable. If it’s slow and buggy, you’re in for trouble - APIs can break! How to fix: use a status page (see AWS), monitor your API (via APIscience.com, for example), and don’t hide (see blog.askimet.com).
#6 You don’t give me tools to help me succeed. The right tools can make all the difference. How to fix: give developers a variety of tools such as a dashboard (see Stripe), a debugger or log (Twilio), a test Sandbox (Twilio again), playground (Google Devs OAuth 2.0), or test console (apigee.com/providers).
#7 You’re marketing to me, you’re not helping me. Developers just plain don’t like marketing – but they love it when you make their lives easier. How to fix: offer self-service instead of making developers call you, have evangelists (see Sendgrid), do events (see Twilio), do hackathons. Now even USA Today is writing about the latter, Musser noted. “Does that mean it’s jumped the shark?”
#8 Your API Is Too Complex - and You Have Your Own Customs. Why would you not go with the flow? How to fix: use REST, use JSON and be pragmatic - Apigee is a good example.
#9 Your TTFHW (time to first ‘hello world’) is too long. Meaning speed is critical – think about how long it will take someone to go from zero to 60. How to fix: start with a great developer experience because UX applies to developers, too. Musser noted that all prior fixes in his talk apply here as well.
#10 You haven’t learned - from the best. Perhaps you forgot to pay attention to the winners in the API world? How to fix: identify and emulate the best role models (like Twilio, Stripe, GitHub, Sendgrid), keep learning (with resources like Gluecon, APIcon, APIconference.com, APIstrat, and more). “An API is a journey, not a destination,” he said.
I asked Musser some questions following his talk:
Q: There seems to be a difference of opinion here at Gluecon about documentation — a speaker said yesterday that, if your product is good, you don't need documentation! What’s your take on that?
“Having a well designed API makes a big difference, but that's not nearly enough. Part of what we think of as ‘docs’ are reference guides (each API call etc.), but you also need to have a good ‘Getting Started Guide,’ good samples, etc, and these all add up to make a big difference.”
Q: There’s also been an attack of sorts on SDKs at Gluecon - I counted at least three speakers who spoke out against them. Where do you stand on that?
“Like so many debates, there's truth and good arguments on both sides. If you don't want or need them, then that's fine. But if done well, they help in many cases. It depends on use-case, developer skill, developer preferences, platform, etc. “
Q: Any other thoughts about making APIs better?
“Seeing these types of issues firsthand over the years, while cataloging thousands of APIs at ProgrammableWeb, what stood out were the frequent issues around API reliability and quality. And so, at API Science, we're focused on providing tools to help companies address these pain points around API health, performance, and availability.”

Be sure to read the next Best Practices article: Companies Revisit API Usage Limits as Markets Change