Oftentimes, enterprises will throw public web APIs out there with the hope that developers will come and build upon them. But then nothing happens. That's because a few essential elements may be missing. Bruno Pedro, an industry consultant and editor, recently took a look at the features developers want and need in the APIs they adopt.
In an economy that depends on companies' abilities to project offerings into markets via APIs, developers are a constituency just as important as paying customers. As Pedro so astutely put it, an API reflects a company and its product, and developers are "the most important thing about your API."
For seasoned software pros, the fundamentals of designing and offering great web APIs are the same as those for any software package put out there since day one — simplicity, documentation, and most of all, live help when it is needed. These principles only need to be tweaked a bit for the API age, but they are still tried and true.
Pedro lists the five most important qualities every web API should have. By the way, these apply to internal APIs shared between enterprise units as well as public-facing APIs:
1. Make it simple to sign up: The key is to treat developers as target "customers," Pedro states. They should "quickly understand the main feature your API is offering and how they can start using it." Pedro cites Ori Pekelman's 3:30:3 rule when it comes to helping developers tap into your API: "On the homepage of your API a developer should: Understand in three seconds the purpose of your API; Be able to identify the entry point in 30 seconds; and Be able to create an account, call the system, and use the result in under three minutes."
2. Provide a sandbox to play in: "A great way to let developers test your API without making them create a real account is to provide a sandbox that mimics all the features without manipulating any real information," Pedro states. "The main difference is that usually the sandbox endpoint will have its own URL." Platforms such as Vagrant and Docker help with the launching of test environments.
3. Provide documentation: Documentation is "the first thing developers look for when they want to start using an API," Pedro states. As part of the documentation, he recommends including sample code, existing API methods, parameters and responses, and input and output formats such as JSON or XML. Also, include details on "exactly how the authorization works and what options are available to developers," as well as an outline of terms and conditions.
4. Provide troubleshooting resources: "In case something goes wrong, there should be available troubleshooting tools and possibly an API status board," Pedro advises. "More often than desired, an API behaves in a way that was not expected by the developer, and it should be easy to understand what really happened." Along with a console, provide an online forum for interactive discussion.
5. Communicate: Keep developers up to date on any changes or upgrades to the API, and always keep the lines open to this important constituency. Pedro also advises employing email lists, blogs, and social media to interact with developers.