APIs and user experience 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, FEMA, OPM, and other agencies and improving them via user experience evaluations. 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 and 18F—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 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 from 18F Demo Day on May 9, 2014.]

Cross-posted from DigitalGov.gov.