Get in touch
Glossary

API Developer Experience

API Developer Experience (API DX) is how easy or hard it is for a developer, and increasingly an AI agent, to go from discovering your API to succeeding with it in production. Emmanuel Paraskakis teaches it as a 4-stage funnel — Discover, Learn, Succeed, Retain — that mirrors a marketing funnel but for developer adoption instead of consumer purchase. It's the practical, measurable version of "is my API good," broken into stages you can actually diagnose and fix independently.

Why it matters

“Good DX” is too vague to act on by itself. Breaking it into four stages makes the diagnosis specific: a developer who can’t find your API has a Discover problem; a developer who finds it but can’t get a working call from your docs has a Learn problem; a developer who gets a working call but never reaches their actual integration goal has a Succeed problem; and a developer who succeeds once but abandons your API later has a Retain problem. Each of those needs a different fix — better SEO and positioning for Discover, better quickstarts and examples for Learn, better error recovery and completeness for Succeed, and better ongoing value or changelog communication for Retain.

This same funnel is the backbone of Emmanuel’s paid DX Assessment engagement, which applies it formally to an enterprise’s full API surface. The free version — the API Developer Experience Canvas — lets any team self-score against the same four stages before commissioning a formal assessment.

How to apply it

  • Diagnose your API against each of the four stages independently — don’t lump them into one vague “our DX is bad” verdict.
  • Use the API Developer Experience Canvas (Miro template) to score yourself stage by stage.
  • Fix Discover and Learn problems first — a developer (or agent) who can’t get through those two stages never reaches Succeed or Retain at all.
  • Revisit Retain specifically for agent consumers — this is where deprecation signaling and stable, versioned behavior matter most.

FAQ

What are the four stages of API DX?

Discover, Learn, Succeed, Retain — the funnel a developer or agent moves through from first finding your API to becoming a long-term user of it.

How is API DX different from API documentation quality?

Documentation is one input to the Learn stage specifically. API DX covers the full funnel, including whether developers can even find your API (Discover) and whether they keep using it over time (Retain).

Does API DX apply to AI agents the same way it applies to human developers?

The stages are the same, but the failure modes differ — agents are less likely to "give up and read the docs" at the Learn stage, and more vulnerable to silent failures at the Retain stage if deprecations aren't machine-readable.

What's the relationship between API DX and a DX Assessment?

API DX is the framework (the 4-stage funnel); a DX Assessment is the paid engagement that applies that framework formally to an entire company's API portfolio.

Where do I start improving my API's DX?

Self-score against the free API Developer Experience Canvas before investing in a formal assessment.