Use Cases

Providing the who, what, how, and why of an API, establishing details about who the intended consumer is, while also linking use cases to specific operations to help align the business and technical details of an API.

Also known as: Scenarios, Recipes, Tutorials

Example

- type: UseCases
  url: https://developers.example.com/use-cases

Standards

OpenAPI Initiative OpenAPI Specification 3.1
OpenAPI Initiative Arazzo Specification (workflow descriptions)
AsyncAPI Initiative AsyncAPI Specification
schema.org schema.org HowTo
Postman Postman Collection v2.1
Bruno Bruno Collections

Media Types

application/json — Postman, Bruno, and Arazzo workflow documents.
application/yaml — OpenAPI and Arazzo workflow authoring format.

OpenAPI Expression

tags (OpenAPI 3.x) — Group operations by audience or use case so documentation reflects intent.
x-use-cases (Vendor extension) — Catalog of use cases each referencing one or more operations.
components.examples (OpenAPI 3.x) — Worked examples illustrate end-to-end use cases.

Governance Rules

operation-description (Spectral built-in (spectral:oas)) — Every operation requires a description anchoring it to a use case.
oas-tag-description (Spectral built-in) — Tags that represent use cases must include descriptions.
operation-tag-defined (Spectral built-in) — Use-case tags must be declared in the global tags array.

Risk & Compliance

Tools

Postman — Collections and runnable scenarios
Bruno — Git-friendly API collections (MIT)
Arazzo Specification project — Workflow modeling (Apache-2.0)
Redocly — Use-case-grouped reference docs (x-tagGroups)
Stoplight Elements — Use-case-driven documentation rendering (Apache-2.0)

Suggested Metrics

use_case_coverage_percent — Share of operations linked to at least one documented use case.
top_use_case_traffic_share — Share of total API traffic explained by the top N use cases.
tutorial_completion_rate — Share of developers who finish a use-case tutorial after starting it.
time_to_first_use_case — Median time from signup to a developer completing the first canonical use case.

Example Implementations

Stripe — Recipes and workflow guides organized by commerce use case.
Twilio — Use Cases section frames products around customer scenarios.
Slack — Tutorials and sample apps organized by integration use case.
Postman — Public collections represent shareable, runnable use cases.