More Partners, Less Effort: API Documentation for the Win

This guest post comes from Erik Schmidt, who works on Application Enablement at Alcatel-Lucent (parent company of ProgrammableWeb).

APIs are a business development tool. Whether you are monetizing directly or indirectly, they allow you to create effective partnerships and expand your Platform faster and more efficiently than ever before. The secret to unlocking the full potential of your APIs is to create Documentation that makes it easy for partners to use them.

Thinking about documentation as a business development Function clarifies what it must do to be effective. Business development is about establishing trust. In the context of APIs you can establish trust by being thorough and very clear about what can and cannot be done with your APIs. The best way to do this is through a layered approach that incorporates an API console, code samples, example apps, and troubleshooting details.

“API consoles” (sometimes called “API browsers”) such as Flickr's API Explorer and the Google API Explorer are very useful. No amount of written explanation can replace the clarity of seeing the API in action, and a console allows anyone to immediately jump in and explore.

Code samples also allow partners to get going quickly with your API. Generating them through an API console is ideal, but providing them as part of written documentation is a minimum requirement. Request and response examples can be tailored to get partners thinking about how they can best use your APIs. They should also cover the syntax from basic to more sophisticated calls, including parameters and expected results.

A completed example app is a very effective way to show your APIs in context. Think about how you want partners to interact with your data and how they can best benefit from it, and build your example app accordingly. If you do it right, they will come up with their own creative ideas as they learn about your APIs.

Coming up with ways to showcase the advantages of your APIs is relatively easy, but establishing trust with partners also requires that you acknowledge things may not always go as planned. Show them how your Authentication works and how errors are handled. The more transparent your approach, the more comfortable partners will be about using your APIs.

Getting the Details Right

When you get past consoles and examples, you still need to provide detailed information about each method, its parameters, and associated error codes. Auto-generated documentation is a good start, but it is always a good idea to run it past a human editor before posting. You do not know what has been left out, simplified, or altered in meaning until you review it.

Since web APIs can be accessed from essentially any language, researching your partner audience will help you determine which languages to use in your example code. Remember that as your APIs mature you will need to update example code accordingly. Instead of trying to cover a wide swath of languages, focus on three or four mainstream languages you know you can support over the long haul. Your likely partners may favor particular languages, particularly if your API caters to a particular industry or market segment. For overall applicability, ProgrammableWeb figures show that for Web API use PHP is the clear favorite, followed by Java. The third tier is comprised of Python, Ruby, Perl, C#, and .Net, and JavaScript.


Most API documentation is strong in some areas and weak in others, but some stand out for their thoroughness. Twilio's documentation starts at the business level with focused tutorials and drills down into technical details. The flickr API provides well-integrated and extensive documentation. Each method can be invoked from the API Explorer, and arguments and error codes are clearly delineated.

Putting It All Together

If you are offering a web API, chances are you are also busy doing a hundred other things. The important thing to remember is that the point of API documentation is to get partners to use them in ways that benefit your business. Establish trust, give partners material they need to be successful, and you'll transform your API documentation into a vehicle for serious business development.

Enabling API and Application Lifecycle Management

APIs have been around for a while, but it’s clear that the growth trend we have seen in the last three years places APIs as the central link to connecting the companies of the future. Alcatel-Lucent’s focus on Application Enablement helps Service Providers navigate this new economic landscape by helping carriers transform their existing data infrastructure into a commercial transaction platform from which they can deliver new services, faster, cheaper and at scale. Alcatel-Lucent provides software and consulting services in the areas of API Management, Analytics, Business Management and Service Composition and Orchestration. If your company is interested in understanding more about how APIs can help you transcend this new information economy, we’d love to talk to you.

Be sure to read the next API article: Font Squirrel API: Commercial-Use Free Fonts and Web Typography