All API contracts must maintain a clear record of their provenance including reviews, certifications, pull requests, and change history, ensuring that the evolution of each API is traceable, auditable, and supports compliance and quality assurance efforts.
API Provenance Is Maintained and Auditable
Policies
Provenance
Helping curate the provenance of each API contract as it evolves over time, documenting change, and cataloging the reviews, validation, certification, and conversation that occurs as each API moves...
Issues
Provide the provenance of an API contract using Git issues.
Pull Requests
Provide the provenance of an API contract using Git pull requests.
Reviews
Provide the provenance of an API contract using API governance reviews.
Certifications
Provide the provenance of an API contract using regular certifications
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.
Logging (Operations)
Require that every API produces structured, correlated logs for each request, so I want a consistent log schema, a correlation or trace identifier carried through, and clear rules about what gets c...
Experiences
Provenance
Failing to understand your API history increases the risk of repeating past mistakes in future API development. Establishing provenance for each API helps track changes over time and ensures new ow...
Quality
The quality of HTTP APIs powering an enterprise tends to decline as the number of ungoverned APIs grows across internal, partner, and public landscapes. Low-quality APIs lead to poor downstream exp...
Trust
Establish trust with API consumers will evolve and build over time, and is something that can be lost in a very short period of time. Trust will depend on other experiences like quality and reliabi...
Compliance
Compliance is the experience of meeting the legal, regulatory, and internal obligations that come with operating an API. For many teams it feels like a burden bolted on at the end, but the reality ...
Governance
Governance is the experience of keeping API operations consistent and aligned as they scale across teams and time. It is the discipline that connects strategy at the top to the rules being enforced...
