Why API Stories Come Before the Spec
Designing intent while change is still cheap
Long before we wrote equations, contracts, or specifications, we told stories.
Not just because they were entertaining, but also because they were practical. A story is how humans remember what matters, how we reason about cause and effect, make sense of the world around us, and pass intent across time and place. Stories help us to grow not just as individuals but also as a community; as a species.
In Western civilization, Aristotle understood this when he described narrative as a way of making sense of action rather than objects. Medieval mapmakers understood it when they drew journeys instead of coordinates. Engineers have always known it, too, even if we don’t always think of architectural artifacts that way. Walkthroughs, scenarios, war stories, postmortems, these are all attempts to explain how a system behaves when someone actually moves through it.
In the world of programming, all too often we skip over the work of storytelling. I think this is especially true with APIs. We jump straight to structure. We write schemas, define endpoints and assume meaning and purpose will somehow emerge later. And sometimes it does. But more often, it does not.
Over the last several years I’ve been developing an API Story process and document format to help designers and developers more easily create and iterate on the work of better API design through storytelling. Of course, the idea of “stories” for programming is not new. We have user stories, job stories, epics, personas, storyboards, etc. These are all an acknowledgment that systems are understood through plot, movement, choice, and consequence, and that explaining those things clearly is a form of design.
So, if stories are an important art of understanding, teaching, and learning, how do API Stories fit into this space? What follows is a short guide to the API Story and some suggestions on how you can apply them in your own work.
Most API failures start before code
Most APIs do not fail (or languish in disuse, resist re-usability, etc.) because of bad syntax, the wrong framework, or an unfortunate tooling choice. Those problems are usually relatively visible and easily fixable. When APIs fall short, the cause is almost always long before production release. Often the intent of the API was assumed instead of stated. And these assumptions were commonly left unexamined and unexplained.
The industry response to a new API problem is often immediate and familiar. We reach for OpenAPI, start naming endpoints, sketch out schemas, and revel in the early flash of productivity. These artifacts are valuable, but they are almost always created prematurely. They describe shape and constraint very well, yet they fail to explain purpose, activity, and choice. They tell us what exists; the “nouns” of the design but not why it exists or how it is meant to be used (the “verbs”).
In effect, I see developers trapped in this pattern of asking structural artifacts to do narrative work. We expect schemas to explain behavior and endpoints to communicate intent. Sometimes that works, usually for simple systems. As complexity grows, it stops working.
And this is often where workflow enters the picture. When schemas and endpoints fail to explain how a system is meant to be used, teams introduce workflow descriptions to compensate. These may take the form of diagrams, step lists, orchestration rules, or external documents that explain “first do this, then do that.”
Workflow can be useful, but it also carries a cost. It encodes one preferred path through a system at a moment in time, often before the system has fully settled. As requirements change, workflows harden, assumptions get baked in, and alternative paths become harder to see or support. What began as an explanation of behavior becomes a prescription for it.
We already know that, as APIs grow to support more use cases, schemas expand and workflows proliferate, often locking in assumptions earlier than intended and making it increasingly difficult to safely modify the underlying elements of the services or even the API itself.
API Stories introduce a deliberate pause at a critical moment early in the API lifecycle. They create space to say, clearly and plainly, what the system is meant to do, who it is for, and how it is expected to behave. And it makes this possible while design changes are still cheap and understanding is still fluid.
What an API Story actually is
An API Story is a structured narrative used to describe what a system is meant to do before decisions about protocols, endpoints, or schemas are made. It captures intent explicitly, rather than leaving it to assumptions that emerge later. An API Story names the states a system can be in, the actions that can be attempted from those states, and the constraints that shape how change is allowed to occur.
This is not documentation polish, and it is not a user story. Documentation explains an interface that already exists. User stories focus on individual needs or outcomes. API Stories exist earlier than that. They describe the system itself as a space that can be entered, observed, and navigated.
In the lifecycle of an API, stories belong after initial ideas and before formal specifications. They should appear once a team has a sense of the problem they are trying to solve, but before that understanding has been locked into rigid schemas, endpoints, and contracts. At this stage, change is still inexpensive, and disagreement is still useful. API Stories allow designers and developers to settle into a quiet zone that exists before making critical decisions.
API Stories are written for humans first. They are meant to be read, discussed, and revised by designers, developers, and subject matter experts together. At the same time, they are structured enough to support downstream automation. A well-written story can later be translated into specifications, diagrams, vocabularies; even implementation-specific mocks, tests, and documentation.
The important distinction is this. API Stories are design instruments. They exist to both reflect and shape thinking. They document the creative problem-solving that should occur before prescribing a narrow implementation.
API Stories model systems as places and moves
At the heart of an API Story is a simple mental model. Systems are composed of places you can be and moves you can make. In the language of API Stories, resources are places and actions are moves. This framing is deliberate. It shifts attention away from storage and operations and toward navigation, selection, and consequence.
Resources represent observable states a client can encounter and return to over time. They describe situations, not containers or collections. A resource provides answers to questions like “where am I?”, “what do I know here?”, and “what options are available to me at this point?” Good resources are stable enough to be revisited, reasoned about, and linked to without ambiguity.
Actions describe intentional attempts to change the state of things. They are not protocol operations or method calls. An action expresses what an actor is able to do next. Crucially, every action leads somewhere. Each action returns a resource, making its outcome explicit. Success and failure are not hidden inside responses; they are expressed as movement to a new or different state.
This is why API Stories avoid workflows. Workflows prescribe a fixed path. Stories describe a broad map. A map shows possible routes without insisting on a single order of travel. By modeling systems as places and moves, API Stories make navigation observable without freezing behavior too early in the process.
As an added benefit, this framing also exposes design problems early. Missing affordances stand out when a state has no meaningful moves. Ambiguous transitions surface when actions do not clearly lead to a well-defined place. Of course, these are design questions best answered before any code exists, while change is still easy and cheap.
A safe place to start
API Stories make a modest claim. They do not replace specifications, contracts, or tooling. Those artifacts are still essential. What API Stories provide is the connective tissue between thinking and building, the place where intent is made explicit before it is locked into structure.
Used consistently, API Stories can preserve meaning as systems evolve. They capture not just what exists, but why it exists and how it is meant to change. When new requirements appear, or new teams inherit the work, the story carries context that schemas alone cannot. Extension becomes safer because intent was never implicit to begin with.
The easiest way to start is also the least risky. Pick a small, new idea, even a speculative one, and write an API Story for it. Describe the states a client might encounter, the actions that would make sense from those states, and the constraints that feel important. Do this before thinking about endpoints, payloads, or protocols.
If you want a concrete starting point, the API Story repository includes an overview, a specification, examples, and authoring templates you can copy and adapt. Use them as scaffolding, not as rules. The value comes from the thinking the story encourages, not from just following a format.
Systems that can be explained clearly tend to change more safely. API Stories are one way to make that explanation durable.
Stories have always helped humans understand how things unfold through action rather than abstraction. API Stories bring that habit to API design, while change is still cheap and thinking is still flexible. If nothing else, try writing one story for a new idea and see what questions it invites you to answer early in the process.