The definition is the contract. OpenAPI, AsyncAPI, JSON Schema, and APIs.json are the machine-readable artifacts I use to describe what an API is before, during, and after it exists. Investing in solid definitions early is what makes every other stop along the lifecycle possible, because almost everything downstream is generated or governed from these contracts.
Definitions
Define
Stop 2
Policies at this stop
Descriptions for APIs
Providing a robust description of each API, providing the right amount of information for consumers to understand what is possible and what the business use case is.
Images for APIs
Including images as part of the metadata for your APIs helps make APIs more visible as part of portals, documentation, and other resources.
Names for APIs
Providing a clear, descriptive, and concise name for each API, as well as the APIs it contains, properly defining the scope, with an intuitive first impression of an API.
Tags for APIs
Tags provide a bounded context for your APIs, providing keywords that help organize APIs by domains, and make them more discoverable.
Unique Identifiers for APIs
Providing unique identifiers for API apis, as well as the APIs that are indexed as part of an API, providing a key reference for discovery and automating around a contract.
Metadata for APIs
Unique identifier, name, description, tags, and other metadata for the API that defines the purpose of each individual API, and how it benefits API producer and consumers, establishing the base of ...
Created Date for APIs.json Contracts
Providing the data in which an API contract was created, establishing the inception of a specific contract involving one or more APIs, which defines the age of the contract.
Modified Date for APIs.json Contracts
Providing the data in which an API contract was last modified, tracking the change that occurs with each API contract, understanding the velocity as well as stagnation of APIs.
URL for APIs.json Contracts
Providing the valid URL for the APIs.json contract, identifying the source of the contract which may or may not be where it is found, helping make contract authoritative.
AsyncAPI Contracts Provided
I require that any event-driven or messaging interface is described with an AsyncAPI document, the same way we insist on OpenAPI for request-response APIs, so that channels, messages, and payloads ...
Base URL for API
Providing a valid URL to the base for an API that is designed for machines to use when making call to an API by an consumer.
Business Contract Validator
The APIs.json business contract must have a link to the validator for each, providing the ability to run linting rules for each type of contract and see the details of rules as they are applied.
Contract Testing (CI/CD)
Require that every API is tested against its own contract in the CI/CD pipeline so the running service can never quietly drift from the OpenAPI it publishes. I insist on contract testing because a ...
Descriptions for APIs.json Contracts
Providing a robust description of the API contract, as well as each API it contains, providing my context for stakeholders of the contract.
Images for APIs.json Contracts
Including images as part of the metadata for your APIs helps make APIs more visible as part of portals, documentation, and other resources.
Names for APIs.json Contracts
Providing a clear, descriptive, and concise name for each API contract, as well as the APIs it contains, properly defining the scope.
Tags for APIs.json Contracts
Tags provide a bounded context for your APIs, providing keywords that help organize APIs by domains, and make them more discoverable.
Unique Identifiers for APIs.json Contracts
Providing unique identifiers for API contracts, as well as the APIs that are indexed as part of a contract, providing a key reference.
Metadata for APIs.json Contracts
Unique identifier, name, description, tags, and other metadata for the contract that defines the purpose of the API Contract, and how it benefits API producer and consumers, establishing the base o...
GitHub Organization README
GitHub organization provide the ability to have a dedicated README, providing a single landing page for the API workspace of a domain, line of business, or domain, where all API contracts can be fo...
GitHub Organization Repositories
GitHub organizations provide teams with the ability to create repositories for managing API contracts, separating and organizing contracts by meaningful bounded contexts within a specific domain.
GitHub Organization Teams
GitHub organizations allow for the management of people and teams to help define who has access to repositories, contracts, and other assets managed via this dedicated domain workspace.
GitHub Organizations
A GitHub organization provides a dedicated workspaces for teams to produce APIs, organize all the API contracts in motion, and leverage source countrol, CI/CD, teams, and other resources provided b...
GitHub Repository
A GitHub repository for an API, providing the single source of truth for the API contract, OpenAPI, and other artifacts, as well as the road map, change log, support, feedback, and other elements o...
Human URL for APIs.json Contract
Providing a valid URL to a landing page for the API that is designed for humans to use when learning more about an API.
OpenAPI
A machine-readable OpenAPI using the most recent version of the API specification, describing the surface area of each API, which is then used to render the human-readable documentation, and other ...
Postman Collection
A machine-readable Postman Collection describing the surface area of the API contract or providing more modular and executable representations of portions of the API contract. - Postman - Executable
Postman Workspace
A Postman Workspace provides a dedicated space to manage API contracts within a domain, complimenting other types of workspaces, allowing for private, partner, and public workspaces to exist for ma...
GitHub Actions
Employing actions as a pipeline to make sure that the deliver of each API is a repeatable process.
Issues
Leveraging issues as a way to communicate API change and feedback.
Pull Requests
Using pull requests to submit changes to business or technical artifacts.
README
Require that each API contract repository has a dedicated README.
Teams
Require that API contract management is controlled using Git teams.
Technical Contract Validator
The OpenAPI technical contract must have a link to the validator for each, providing the ability to run linting rules for each type of contract and see the details of rules as they are applied.
