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
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!).
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)
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
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.
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.
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)
Tweak the final bits, find perfection.
Mock up the API in full detail
Decide on the fine details. Use usability testing 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.
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.