_posts/2014-05-10-make-gov-apis-better-with-user-experience.md
---
layout: post
date: '2014-05-10T13:01:00-04:00'
tumblr_url: http://18fblog.tumblr.com/post/85329171105/make-gov-apis-better-with-user-experience
title: "Make government APIs better with user experience"
description: "An API is a product just like a car, a website or a ballpoint pen. It’s designed to help someone do something. Products are either designed well—they meet expectations and deliver value—or they are designed poorly and create frustration and confusion. Inevitably, bad products are abandoned without a thought, like an old T-shirt with holes in it."
excerpt: "An API is a product just like a car, a website or a ballpoint pen. It’s designed to help someone do something. Products are either designed well—they meet expectations and deliver value—or they are designed poorly and create frustration and confusion. Inevitably, bad products are abandoned without a thought, like an old T-shirt with holes in it."
image:
authors:
- jonathanrubin
- gray
tags:
- usability
- api
- user-centered design
- best practices
---
[APIs](https://www.digitalgov.gov/2013/04/30/apis-in-government/) and
[user
experience](http://www.usability.gov/what-and-why/user-experience.html)
go together like gummi bears and ice cream.
An API is a product just like a car, a website or a ballpoint pen. It’s
designed to help someone do something. Products are either designed
well—they meet expectations and deliver value—or they are designed
poorly and create frustration and confusion. Inevitably, bad products
are abandoned without a thought, like an old t-shirt with holes in it.
So for the past few months we have been taking APIs from
[USDA](http://ers.usda.gov/developer#.U2p8rPldUq4),
[FEMA](http://www.fema.gov/developer-resources),
[OPM](https://data.usajobs.gov/), and other agencies and improving them
via [user experience
evaluations](https://www.digitalgov.gov/resources/digitalgov-user-experience-program/digitalgov-user-experience-program-test-support/).
We bring together agencies and their customers—private-sector developers
who use APIs every day—and ask the developers to maneuver the APIs and
documentation. These developers provide a live critique of the APIs and
identify problems and stumbling blocks to using them.
Bing! Instant and unfiltered customer feedback.
And who are we? We’re two GSA programs—[DigitalGov User Experience
Program](https://www.digitalgov.gov/resources/digitalgov-user-experience-program/)
and [18F](https://18f.gsa.gov/)—who care about creating better digital
products. We improve federal systems and teach people about user
research, all in one morning.
The promise of APIs is incredible and their widespread adoption is a key
part of 21st century government. But APIs are only worth the sweat and
tears that go into their creation if people can use them. Our program
has helped more than a dozen agencies realize the benefits of User
Experience evaluations.
And we’ve learned a lot along the way:
**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.
We’ve also assembled an [agency
checklist](https://18f.github.io/API-All-the-X/pages/agency_checklist.html)
that API producers can use as they grow out and mature their efforts.
It’s a living document, so feel free to suggest edits! We’re trying to
schedule these sessions monthly, going forward. There is still very
little out there on the subject of API usability, so we’re documenting
everything and will share it with you all shortly.
[Editor's note: you can also view Gray Brooks' [slides on API usability
testing](https://speakerdeck.com/18f/api-usability-testing-18f-demo-day-9-may-2014)
from 18F Demo Day on May 9, 2014.]
*Cross-posted from
[DigitalGov.gov](https://www.digitalgov.gov/2014/05/09/make-gov-apis-better-with-user-experience/).*