How the Department of Labor gets API Documentation Right

One of the long held truisms of API development is that creating quality documentation is vital to the health of your API program. On the DigitalGov site, Bill Brantley highlights the Department of Labor’s API documentation and how it fulfills four important functions that all API providers should strive for when crafting their documentation.

Starting with the DOL’s main API page, developers are given explanations of what the API does and the value that it can provide. This is the first of the four functions described by Brantley. Developers are also given the choice of following the path that best suits them given their familiarity with the API.

The second important function of documentation is that it should explain how to get started installing and using an API. Looking at the first page of the beginner’s guide, developers are shown the steps needed to register, create an API Key, and access the API via a URL.

The DOL does a good job of putting their sample code in a place where it is easily found. Both the developer and experienced paths show links to SDK documentation, GitHub repositories and more; all organized by one of eight languages. In addition, they offer examples of applications for both mobile and web.

Lastly the developer site provides reference to all the functions and data elements of the API. The documentation is straightforward including example URLs, errors codes and comments. While not as slick as the documentation one may find for the Stripe or Twilio APIs for example, it meets the requirement spelled out by Brantley.

 

Original Article

The API Briefing: How Do I Use This API? Good Documentation Practices from Department of Labor

Wendell Santos is the editor at ProgrammableWeb.com. You can reach him at wendell@programmableweb.com. Connect to Wendell on Twitter at @wendell78 or Google+.

Comments