When creating an API, it’s all too easy to release something that “just works.” For some developers who aren’t working at an API-first company where the API is a central component to their business, they may see creating an API as a distraction from their core duties and rush to get a product out that does the job it’s supposed to, but little more than that.

At first glance, that might sound like an MVP (minimum viable product) but there are a few key differences between the two situations:

• MVPs are designed to evolve based on customer feedback, while end users are more likely to accept APIs “as is.”
• An MVP will generally be up against other products while an API may be the only solution available in a certain niche.
• Whether B2B or B2C, an MVP has customers who are truly invested in how it works and where it’s heading. An API rushed to market is more likely to be viewed fairly apathetically by both providers and consumers.

API design standards have come along way, but still the result is a) it’s easy to put out a sloppy API without getting much heat for it and b) APIs can continue to be sloppy without much pressure to change.

Things really shouldn’t be like this. An effective and usable API can unlock new market segments, create partnership possibilities, and become an extremely useful tool in your company’s creative toolbox. With all of that in mind, we wanted to summarize the main factors that have a huge impact on how usable an API is.

1: Design/Experience

Plenty has already been written about this, including on our blog, but it bears repeating once more. We’ve previously quoted Ronnie Mitra, director of API design at the API Academy, who has the following to say about API design:

“If your API is poorly designed, poorly documented and poorly supported and they’re not required to use it, you can bet they won’t.”

Granted, it’s easier said than done to creative a truly effective API, but it’s something we believe those building an API should always be aiming for. Whether you want to call it Developer Experience (DX), Design, or something else, it’s important that API providers do as much as possible to make implementing an API as straightforward as possible. DX involves increasing transparency with accessible documentation, decreasing onboarding time, and improving the aesthetics of your developer portal on all fronts.

2: Technology

How will your web service be accessed? In refining the underlying API stack, match technology to what your developer audience want to consume.

• Protocols: Consider how you want your data to be accessed REST, SOAP, Apache Thrift, etc.
• Formats: Support return types that are relevant to your audience and their consumption habits (JSON, XML, etc). In certain enterprise, government, and open data API initiatives, this could even be CSV or PDF.
• Hypermedia: Consider adding controls that enable smart navigation, tagging, pagination, and more.

3: External Testing

There aren’t many circumstances in which you’d release a new product into the wild without testing it on a focus group of potential or existing customers. Apply this same product mentality to API product ownership.

Services like Peek make it easy for copywriters, designers and developers to get some quick insight into what people think about their site. Unfortunately, the need for technical expertise means that it’s more difficult to get this kind of feedback from potential API consumers.

Releasing an API as an open beta and actively monitoring a feedback forum is not a bad idea because it reassures developer consumers that, if there are problems with the API, there’s at least some chance that they’ll be addressed over time.

Merely having an open beta status encourages feedback far more than a traditional release. Amplifying testing features could involve offering virtual environments for developer users to model API behavior in their application development processess.

4: Status/Changelog and Documentation

Properly managing API endpoint statuses is key to keeping users happy. Something like MailChimp’s solution (https://status.mailchimp.com) is a nice way to keep people in the loop and establish credibility with great uptime rates:

On the off chance that something goes wrong, good ways to notify API consumers (other than a status page, like MailChimp uses) are to send out email alerts or share a status update on Twitter.

MailChimp also maintains a thorough changelog, offers an API playground, an error glossary, a list of best practices, along with many and other guides. The result is that their Developer area feels just as welcoming to complete newbies as those who’ve been working with APIs for years.

Properly describing your API responses with comprehensive error codes is critical for creating usable web APIs. Sometimes things go wrong and that’s ok, as long as messages arising from errors (whichever side they’re on) explain how to remedy them.

	
		400
		Dial: Invalid phone number format 
13223
		https://www.twilio.com/docs/errors/13223 
	

There’s nothing less helpful than an unclear, unstructured error that leaves you scratching your head. The Twilio API error response shown above is a great example of how NOT to leave one confused — it has a straightforward error message with a link to get more information on what caused it and how to remedy it.

5: Tone

Don’t be afraid to have a little fun with your APIs. Making it clear what the API does is probably the most important task in the API creator’s rulebook, but doing so using dry language is the easiest way to get people to switch off. Investing a little time documenting the API in a way that’s succinct, readable, and maybe even (shock horror) makes people smile, is a surefire way to get people engaged with the API itself.

Twitter does a pretty good job of this, with developer-targetted copy on pages like this one. They sometimes come across a bit too pseudo-aspirational at times, but their content is generally concise and easy to understand.

There’s an old adage that’s popular among copywriters, and that’s to be “fun, not funny.” Trying too hard to be funny is never a good thing, but going with a tone that’s cheerful and lighthearted will encourage people to stick with your documentation rather than trying to tackle everything on their own.

6: Speed/Scalability

Whenever one talks about usability, the issue of speed inevitably rears its head. Look, for example, at the ways in which REST has improved on SOAP. A few of the advantages of REST, of which there are many include:

• Simpler, more intuitive solutions
• Quicker output
• Easier to scale
• Allows would-be API consumers to plug into a service more effectively

There’s a reason why the community has embraced RESTful principles in the way it has — it’s often the right tool for the job. When hypermedia and RESTful design promise to shake up the way APIs function, make APIs quicker and easier to implement, and encourage keeping APIs as up-to-date as possible, it seems foolish not to embrace them.

That doesn’t mean that you need to jump on the back of every single fad that rears its head, only that keeping up with best practices might just help you figure out that one issue that’s stopping your API from becoming a more valuable part of the ecosystem you’re functioning in.

7: Efficiency

When it comes to building an API, efficiency is all too often something of an afterthought. Sometimes the focus is misplaced; for the provider it becomes more about what is accomplished, rather than how it is accomplished.

When we talk about efficiency, we’re talking about both technical efficiency (e.g. pagination, number of calls, the structure used, size of stack etc.) but also the impact that it has on how the API actually functions; things like speed of calls, availability, output formats and so on.

An API is only as good as the experience someone had the last time they used it; APIs that are consistently slow or unreliable will hemorrhage users who don’t have to use it and invite seemingly endless criticism from those who do. All of which will give you a nasty headache…

7.5: Code Libraries

This point doesn’t get a number of its own, as it’s more of an offshoot of efficiency, but helper libraries that cater to different languages instantly makes dealing with an API more appealing to a wider developer audience.

Twilio is one of the best around at this with over 15 different languages catered for in their Libraries section, although the majority of this documentation has been collated by their developer community.

8: Ongoing Maintenance

We’ve already mentioned documentation and error messages above, but there’s more to upkeep than just these things. In order to keep your API from being a flash in the pain, and ensuring that its usability improves (or at the very least remains constant) you may want to think about:

• Creating an effective developer community – mailing lists, Google groups, Slack chats, however you want to go about it.
• Building re-usable libraries/best practices for new users, which should also reduce the number of errors you have to deal with.
• Proper versioning that doesn’t disrupt those still using the previous version until a final scheduled deprecation occurs.

The above is a good start but, but to add your own points to that list, just think about the APIs you can’t stand using and replace their pain points with usable methods.

Final Thoughts

The answer to the question of “what makes a usable API?” is, like so many things, “it depends.” But depends on what?

• What its potential users looks like and their level of expertise.
• The designated purpose of the API itself, and how often it needs to push/pull data.
• The core provisioning strategy. Private, public, or partner APIs will inherently have different exposure of documentation and access.

Yes, there are factors that should always be constant (speed, following good naming principles etc.), but there are many others that will vary considerably. When you begin to consider issues like those listed above, you start to get a picture of what your API should look like, promoting a greater emphasis on the entire API product lifecycle.

And if all else fails and you’re drawing a total blank, ask someone who’ll be using it what they want it to do. That should get you off to a good start.