Jenny Wanger - The UX of DX: User Testing in the Invisible World of APIs

API the Docs Virtual Event Series 2020 Recap

This talk was presented at API The Docs Virtual 2020 event series on 22 April. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit the API The Docs 2020 recaps overview to explore all presentations from 2020. API the Docs Virtual begins May 2021! CFP closes February 28, 2021.

Jenny Wanger



Jenny's presentation



Jenny's slides

How to improve API usability by applying UX methods?

  • Build what developers need, not only what they or internal teams want.
  • Ensure great docs by having great APIs underneath.
  • Speed up coding.

The design framework: structure

1. Discovery

Build something that people need.

  • The purpose of the API

Bring everything and everybody in (end users, design, data, product, ...) to understand the problem to solve. Think about business strategy (also for internal APIs!).

  • Techniques

    • Interviews (what are people trying to do and why?)
    • On-site visits (what are customers doing, how do they work together?)
    • Ethnography (talk to customers that the developers serve: what are their needs? + how do the developers learn, process information, solve problems? This information can influence API design)

  • Key equations

    • Observation over conversation (what do the developers do? Bring someone in with a different perspective)
    • Developers + end users
    • Look for the point of marginal return

2. Taxonomy

Navigate broad pieces easily, understand the major steps.

  • Approaching the API: overall flow & naming conventions

Have ideas about who your customers are, who you are trying to serve. Create different journeys. Find the balance between the developers’ mental models and the industry of the business they are working in.

  • Techniques

    • Card sorting
    • Tree testing

3. Mock & prototype

Correct underneath structures.

  • Deeper structures and outlines

Think through the structure of the API request & response body. Get a basic outline of each endpoint.

  • Techniques

    • Paper prototypes (print the API code / share it in a google doc + hand it over to a developer to talk through it and tell what they think about it)
    • Instant Messenger APIs (e.g. through slack, or any other tool to communicate: let developers express assumptions)

4. Usability

Tweak the final bits, find perfection.

  • Mock up the API in full detail

Decide on the fine details. Use usability testing techniques.

  • Techniques

Usability testing via Postman or Swagger. Needed: clear steps and moderation guide.

5. APIs that are live today

Just as with new APIs: iterate! Don’t let an already-built API stop you from building the right API.

  • Assess the API through design research (understand the gaps).
  • Create a vision of where you want to be.
  • Version.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.