2 Identifying API capabilities

This chapter explains how to identify the right capabilities for an API by starting from user needs and working in natural language before touching any programming interface. Capabilities are defined as the combination of use cases users must accomplish and the generic operations that make those use cases possible. The author stresses “form follows function,” collaborative iteration with stakeholders from the Define and Design stages, and the risk of misaligned capabilities that make APIs hard or impossible to consume. To structure the work, the chapter introduces a practical methodology—the API Capabilities Canvas—that turns rough business input into a precise, versatile set of capabilities.

The process begins by walking nominal (happy) paths: list users, the use cases they perform, and decompose each use case into concrete steps, capturing for every step its inputs and successful outcomes. By tracing where inputs come from and how outcomes are used, missing steps, users, and use cases surface early. A second pass explores alternative paths and failures: describe what can go wrong, why it happens, and how to fix it, and add non-nominal branches and secondary users/use cases. With flows mapped, steps are then refined into unique, context-agnostic operations that can be reused across scenarios, avoiding near-duplicates and over-specific actions. Programming interface design decisions are intentionally deferred to keep attention on capability accuracy and to accommodate later constraints.

Throughout, the chapter sets guardrails to keep the API focused and resilient: stay within the scope established in the Define stage, ask “Why?” to uncover root needs and eliminate noise, and avoid two common pitfalls—overfitting to a specific consumer (e.g., mirroring a UI flow or absorbing consumer-side business logic) and leaking the provider’s internals (e.g., data organization, internal business rules, or service boundaries). Using a shared, natural-language vocabulary and lightweight tools (such as a spreadsheet canvas or diagrams), designers iteratively validate with stakeholders until there is consensus. The result is a balanced, reusable, and secure set of operations that align with real needs while remaining adaptable to new contexts.

We analyze the needs from the Define stage of the API lifecycle to identify the versatile API capabilities that meet them and other unknown needs. We’ll iterate with the Design and Design stages stakeholders.

API capabilities are use cases and the operations needed to achieve them. We describe them in plain English and keep programming interface concerns for the next stage because form follows function.

We walk through all use cases' nominal, alternative, and failure paths. Then, we refine steps to identify unique operations. Finally, we ensure capabilities fulfill expected users' needs without being too consumer-specific or exposing inner workings.

Different steps may share the same unique operation.

A pivoted API Capabilities Canvas where data is reorganized around operations.

When walking the nominal path, we focus on the ideal and successful paths of the most common use cases. We wonder who (users) does what (use cases) and how (steps). We also identify steps' inputs and successful outcomes to spot missing elements.

Identifying users ensures exhaustively listing use cases. Breaking down use cases into steps will help us identify all operations.

Inputs and success outcomes are essential for understanding the needs, identifying and designing operations, and spotting missing elements.

Investigating the "Buy products" steps' input sources and success outcome usages allows us to spot a missed step and use case.

Investigating the "Search for products to buy" steps' input source and success outcome helps us spot new elements.

To complete the analysis, we investigate the alternative users, use cases, and branches set aside during the first pass and analyze what happens when the steps' fail.

Investigating the failures of the "Buy products" steps, their causes, and how to fix them helps identify a new step.

Asking "What if …​" helps to identify a non-nominal branch on the "Buy products" use case.

Checking if there are similar steps or digging to find each step’s true intent allows us to identify unique and context-agnostic operations.

We identified unique and versatile operations for each step of the "Buy products" and "Fill catalog" use cases. Three operations appear on more than one step.

UI-specific flows are less reusable and flexible than context-agnostic flows.

Exposing database structure through an API makes it complicated to understand and use.

Delegating business logic to the consumers can lead to system and data corruption.

Exposing underlying system architecture can make APIs complicated to understand and use.

FAQ