Usability Testing + Gov APIs = Best

Apr 29, 2013

Good APIs can transform intimidating data sets into something that people can use. Good government APIs can create a better connection between government and citizens. The Digital Government Strategy has spurred Federal adoption of APIs, and the Digital Services Innovation Center and DATA.GOV teams are supporting these efforts by releasing a swath of guidance and resources, hosting online education series and launching a number of hosted tools at Labs.Data.gov.

Always looking to build off other successful programs, we looked to GSA’s First Fridays usability testing program. That team regularly hosts half-day sessions to provide actionable usability feedback for websites. We wanted to see how that model could assist agencies make their APIs programs better–and more usable.

Seven energetic API teams – the Federal Communications Commission, Energy Information Administration, General Services Administration, Economic Research Service, National Institutes of Health, Census Bureau, and USA.gov – signed up to spend a morning with our pilot API usability evaluations.

We found equally energetic volunteer developer testers to run through the agencies’ developer portals, API documentation, and even the actual API endpoints – taking on the role of a citizen developer looking at this material for the first time. By sharing aloud their thoughts and reactions at each stage, these fresh perspectives from experienced developers offered tremendous value.

While the agency API program teams received plenty of feedback to build on, a number of consistent developer needs stood out as practices that all agencies with developer portals need to address. Here are a few.

API Usability Good Practices

Make a Hub

  • Create a central developer hub with a path to each of your APIs and all related resources.
  • Make your hub findable by using a common URL: www.agency.gov/developer
  • Every API in your central hub should have a homepage with links to all of its related resources.
  • Offer clear and user friendly navigation throughout the developer hub.

Provide good documentation

  • API documentation should be in web pages, not a PDF or a Word Document.
  • Provide interactive documentation such as Swagger or I/O Docs.
  • Provide consistent layout, structure, design, and resources for each set of API documentation.
  • Highlight the API endpoint and example URLs early so that developers can jump right in!

Communicate with your developers

  • Plain language helps everyone – beginners and experts. Ask yourself: Would someone who is new to our agency’s work understand this?
  • Give people an overview: what the data is, what you can do with it, how to get started
  • Avoid acronyms.
  • If you require API keys in order to interact with the end point, be sure to allow instant registration. If developers have to wait–even minutes–before they can interact with the data, they will go elsewhere.
  • Provide a means for developers to sign up for updates or see the latest news for these APIs.

Don’t just tell them, show them

  • Include plenty of examples (and go ahead and hyperlink them for convenience). Offer code samples and examples of applications that consume the API.
  • Share code samples, SDKs, and other developer resources through your agency’s GitHub account.
  • Include JSON support. Offering JSONP support also goes a long way to encouraging re-use on third party websites.
  • If API returns are lengthy, offer pagination.

One prime example of government adopting developer norms is the recent API Standards released by the White House. Check it out and we will spend more time on that later!

GSA

Apr 29, 2013