Most developer platforms don’t know they’re bleeding signups.
Someone signs up. Tries to authenticate. Hits a confusing error. Closes the tab. You see the signup in your analytics. You don’t see the exit.
This happens because teams treat onboarding as a documentation problem. Write better docs. Add more examples. Hire a technical writer.
That might help. But it misses the real issue.
APIs have interfaces too
As Jenny Wanger pointed out in her DevRelCon talk on API usability, “APIs do have an interface. It’s just not visual. It’s a code-based interface, but people are still asking you for information, and you’re still having to give information back” [1].
That code-based interface can be designed well or poorly. Research shows it’s usually designed poorly.
What makes APIs hard to learn
Martin Robillard ran a field study watching developers try to learn unfamiliar APIs [2]. The obstacles weren’t random. They were patterns that showed up again and again.
Finding the right elements. Developers need to figure out which classes, methods, or endpoints to use for their task. If your API’s structure doesn’t match how they think about the problem, they get stuck searching.
Understanding what elements do. Once they find a method, they need to know what it actually does. Vague names kill them. Missing parameter details in docs kill them. Unclear return values kill them.
Dealing with conceptual complexity. Some APIs force developers to understand too much internal architecture just to make one simple call. Clarke and Becker’s research on class library usability describes this as the “Working Framework” dimension: what’s the size of the conceptual chunk someone needs to keep in their head to work effectively [3]?
Three design failures that kill adoption
Here’s where platforms create unnecessary friction, based on the research and Microsoft’s API design practices [4].
Credential mazes. Authentication should be simple. If developers have to navigate multiple dashboards, acknowledge legal modals, or hunt through settings menus just to generate API credentials, you’ve already added cognitive load that has nothing to do with their actual task.
Inconsistent naming. Developers rely on conventions. Your API uses a non-standard header name for authentication? They’ll try the standard one first. It won’t work. They’ll assume your API is broken. Microsoft’s REST API guidelines explicitly recommend following established patterns for exactly this reason [4].
Silent failures. Microsoft’s guidelines point out that when an API returns 400 Bad Request, the response body should contain information about the error or a link providing details [4]. Most APIs ship with bare status codes. No explanation. No guidance on how to fix it.
Wanger gives a real example from Weather Underground’s API. Look at the response: it returns fields like fcttext (forecast text) and fcttext_metric. But what about the precipitation field? Is it percent? Inches? Centimeters? The API doesn’t say [1].
Testing reveals what you can’t see
Clarke and Becker’s research on class library usability at Microsoft found that internal teams can’t see their own API’s problems [3]. You know where the credentials live. You understand the conceptual model. You wrote the code.
Their approach was straightforward. Give developers tasks to complete using the API. Record them. Watch for patterns of confusion.
What did they find? “Developers had difficulties creating and manipulating multiple classes to accomplish some task not because the amount of code they had to write was excessive, but rather it was unexpected” [3].
That’s the key word. Unexpected.
Your API might work fine if developers already understand your mental model. They don’t.
This matters for revenue
Better developer experience affects business metrics directly. Easier onboarding means better conversion. Clear error messages mean less support load. Consistent patterns mean faster integration.
The easiest tool to adopt often becomes the standard. Not the most feature-rich.
If you can’t get developers past authentication and their first successful call without confusion, you’ve lost them. Unlike a visual interface where you can watch someone struggle with a button, you probably have no idea it happened.
References
- Wanger, J. (2017). “The UX of DX: user testing in the invisible world of APIs.” DevRelCon London 2017. https://developerrelations.com/talks/ux-of-developer-experience/
- Robillard, M. P. (2009). “What makes APIs hard to learn? Answers from developers.” IEEE Software, 26(6), 27-34. http://dx.doi.org/10.1109/MS.2009.193
- Clarke, S., & Becker, C. (2003). “Using the Cognitive Dimensions Framework to evaluate the usability of a class library.” Proc. Joint Conf. EASE & PPIG 2003, 359-366.
- Microsoft. (2024). “Web API Design Best Practices.” Azure Architecture Center. https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design