An API Use Case is a machine-readable description of how an API is actually meant to be put to work—capturing who is using the API, what they are doing with it, how, why, and where, and tying that story down to the specific OpenAPI operations involved. Use cases align the business and technical sides of the API conversation, making sure that the reasons an API exists stay connected to the endpoints that deliver on them. They are one of the most useful building blocks for keeping producers focused on real consumer value across the API lifecycle.
An API Use Case is an API Commons building block—an open, machine-readable schema that can be used as a common property, or as an individual API property, within an APIs.json. It is indexed as a Common type within its APIs.json index, letting it be discovered, referenced, and reused across the APIs.json ecosystem and surfaced through apis.io. This schema is just getting started, and the process and the schema will mature as it is applied across more APIs.
- use-case-schema.yml — The JSON Schema that defines a use case.
- use-case-example.yml — A worked example describing a single use case.
- apis.yml — The APIs.json index for this building block, referencing the schema and example as
Commonartifacts.
The use-case-schema.yml defines each use case as an object with the following properties:
- who — Who (person or demographic) is using an API, focusing on the person, team, company, or demographic behind usage.
- what — What the consumer is going to do with the API, focusing on the big picture of the application or integration.
- how — How a consumer is going to use an API, focusing on the technical details of programming language or integration.
- why — Why the consumer is going to use an API, getting at the incentive that motivates a consumer.
- where — Where the API will be used by the consumer—on-premise, in the cloud, and other geographical or regional details.
- operations — An array of the unique OpenAPI
operationIdvalues that apply to this use case, ensuring technical alignment.
The use-case-example.yml file describes a single use case:
who: APIs.io Website Developer
what: Open-Source API Search Engine
how: Client-Side Javascript Calls
why: Power the Network Websites
where: Static GitHub Pages Websites
description: This is the initial and primary use case for APIs.io website...
operations:
- searchAPIs
- addAPIsUse cases are one of a growing set of API Commons building blocks that describe the business and technical realities of API operations in a machine-readable way. Because a use case references OpenAPI operationId values, it forms a direct bridge between the business story and the technical contract. It cross-links with the change log, road map, teams, plans, guidance, policies, and other building blocks—each a small, reusable schema that can stand alone or be composed together within an APIs.json index.
This work is in an early stage of development and is rapidly moving as it is applied across a variety of user interfaces and approaches to API operations and governance. If you would like to contribute, have any questions, or would like to inform the work happening, please submit a GitHub issue on this repository or email kin@apievangelist.com.