Friday marked the one year anniversary of President Obama’s open data policy, which requires agencies to collect and create information in machine-readable formats. The order encouraged the release of some high-volume, bulk data sets as application programming interfaces, or APIs, which allow developers to pull the data directly into applications and programs.
The Obama administration has argued that properly formatted government data fuels private sector innovation and economic growth. Nextgov has been tracking this phenomenon in a special report called Government Data Unbound, which notes that much machine-readable government data would be a lot more useful if it was better formatted.
In coordination with other open data programs, the Obama administration has been looking at how exactly to make APIs more useful. On Friday, Jonathan Rubin of the General Services Administration posted this list of API tips:
1. Developers want to start using the API immediately.
No matter who they are, developers begin to lose interest fast if they can’t begin using your API right now. Include links to the endpoint at the top of your documentation. If you require API keys, the registration process must be self-service—requiring someone on your team to act in order for the developer to be able to get started at all, will cost you more developers than you’ll keep.
2. Interactive documentation has become the norm.
There are countless free and easy-to-use options for offering interactive documentation or data explorers that let developers build and test queries. You’ll want to include these since the best way for developers to understand how to use your API isn’t to read more documentation, but rather to see the API in action.
3. Don’t. Speak. Government.
Avoid acronyms, insider terms, and obscure abbreviations. You’ll document a better API for all users, including traditional partners, if you force yourself to step into the shoes of someone new to your sector who doesn’t get the lingo. Build queries around plain language that would make sense to anyone.
4. Never stop listening to your users.
Robust user testing during the pre-production and post-production phases is critical to ensuring that you keep improving the developer experience. Promote a convenient and publicly-facing feedback engine so that developers can give you useful feedback but also take heart in seeing you be responsive.
5. Keep Iterating
Every mature API program realizes that it can continue to improve. If you aren’t regularly making user-centric improvements to your API, you’re letting it fall behind.