By Teresa Torres · producttalk.org · @ttorres on X · LinkedIn
Teresa Torres argues that API teams need product discovery because customer-facing APIs are products, and gaps in them cost adoption. She identifies six recurring usability problems developers hit when learning a new API: weak documentation, poor endpoint coverage or design, limited resource access, confusing error codes, unclear authentication, and sloppy REST conventions. Because APIs create strong lock-in once implemented, making them easy to adopt is a major lever for retaining customers. She recommends testing documentation with real developers before writing code and grounding design decisions in customer mental models and needs.
01Key takeaways
- Treat your API as a product and measure how quickly developers reach first value.
- Write and test documentation with real prospective customers before implementing the API.
- Design endpoints around the mental model customers already use in your main product's interface.
- Write error messages that name the exact field and expected type so developers know what to fix.
- Verify your authentication options match the actual use cases customers have, not just your own.
02Key sections
- Why API usability matters
- APIs are products, and friction during onboarding reduces the chance developers will get value from them. Strong lock-in makes early adoption especially important.
- Documentation and the curse of knowledge
- Documentation is the most common failure point, often written from expert knowledge that customers lack. Testing docs with prospective customers through paired-programming sessions reveals gaps before building.
- Endpoint design and resource access
- Endpoints should match the mental model customers already hold from the GUI, and exposed fields and actions should reflect what customers actually need to do.
- Error codes, authentication and REST norms
- Vague error messages, mismatched authentication models for the customer's use case, and inconsistent REST implementations all force trial-and-error learning that discovery could prevent.
- Connecting problems to discovery
- Each gap traces back to a mismatch between the API team's assumptions and customer needs, which interviews, opportunity mapping and assumption tests can surface.
03From the post
“Last week, I shared that we often get asked, “Do API teams need to do discovery?” You won’t be surprised to hear my answer is yes. I even recorded a short video about the topic: But to really get the point across, I’m writing a multi-week series”
04Frameworks mentioned
Summary and takeaways written by PM Atlas; quotes are short excerpts. © the original author.