An API capability is a user-facing function or group of functions that satisfies a need. It includes the use cases an API must cover and the generic operations needed to achieve them. Describe capabilities in stakeholder-friendly natural language before choosing HTTP paths, programming representations, or data models. section 1.6.1 section 2.9
Identify capabilities from user needs rather than provider internals. Start with users and use cases, decompose each use case into steps, and record inputs, successful outcomes, failures, and errors. Analyze nominal paths first, then alternatives and failures. Map similar steps to unique, context-agnostic operations that can support existing and undiscovered use cases. section 2.1.1 section 2.2.1
From user need to reusable operation
For a social-network backend, users may want to “Check friends’ activities” or “Send a message to a friend.” The latter can involve listing friends, selecting one, and sending the message. Express the capability as “Send a message,” then decide later whether its interface becomes POST /status, POST /messages, or another representation. Likewise, “Upload a photo” can serve both “Sharing a status” and “Changing user profile photo.” section 2.1.2 section 2.1.4 section 1.6.1
Validate a capability set before designing its interface:
- Clarify vocabulary and contradictions, such as whether a status is a message or a private message. section 2.1.5
- Challenge vague, over-broad, consumer-specific, or implementation-driven requirements, and ask why repeatedly to uncover the actual need. section 2.1.5 section 2.6.3
- Check that important actions remain visible as capabilities: “Close an account” may deserve an independent operation rather than a status update. section 9.9.2
Figure 2.3 We walk through all use cases' nominal, alternative, and failure paths. Then we refine steps to identify unique operations. Finally, we ensure that capabilities fulfill expected users' needs without being too consumer-specific or exposing inner workings.
Use the workflow to walk through nominal, alternative, and failure paths, refine steps into unique operations, and verify user-need alignment. section 2.2.1
