The API Briefing: How Do I Use This API? Good Documentation Practices from Department of Labor
When I first started coding using BASIC on the Commodore 64, I rarely documented my programs. Neither did many of my fellow programmers which led to numerous hours trying to figure out just exactly how a program worked. Documentation became more vital as programs became more feature rich and complex. In the API world, there are a number of documentation standards to choose from when documenting an API.
No matter which documentation standard is chosen, make sure that the documentation fulfills these four functions. First, explain what the API does and how it helps the user. Second, explain how to install the API and start using it. Providing code samples and examples of the API in use is the third function. The fourth function of good API documentation is a reference to all the functions and data elements of the API. The API developer may also want to include a section on common errors and how to troubleshoot the API.
Good documentation starts with commenting your code. Every programming language has a way to include comments in the code, and there are applications that will parse the code and pull out the comments to create documentation. Developers can also use tools such as Swagger to produce interactive documentation and automate the API documentation process.
Many federal agencies do a tremendous job of documenting their APIs and data sources. One of my favorites is the Department of Labor’s API documentation. When you first visit Labor’s developer page, you can choose the beginner’s path or the expert path. Choosing the beginner’s path takes you to a page that fulfills all four functions of good documentation. There is a general overview of the APIs and the data sources along with plenty of code samples for eight of the most common API programming languages. Click through to specific data sources for the API reference information, which is housed on GitHub.
The best API documentations are the ones that are structured like tutorials. For example, examine how Labor’s Ruby Government Data SDK Sample is broken up into a detailed set of steps, from installing the SDK to securing the application to running the application. Making an API easy to use is the best way to ensure that the API will be used. Federal agencies realize this, and that is why their API documentation is some of the best.*API – Application Programming Interface; how software programs and databases share data and functions with each other. Check out APIs in Government for more information. Each week, “The API Briefing” will showcase government APIs and the latest API news and trends. Visit this column every week to learn how government APIs are transforming government and improving government services for the American people. If you have ideas for a topic or have questions about APIs, please contact me via email. All opinions are my own and do not reflect the opinions of the USDA and GSA.
