Governance is how everything on this lifecycle stays aligned as an operation scales. Policies, rules, and standards applied consistently across teams are what keep APIs coherent without slowing everyone down. Good governance is enabling, not policing.
Governance
Production
Stop 27
Policies at this stop
Change Log Date
The date of the change that was made to an API.
Change Log Details
The description of the change that was made to an API.
Change Log Title
The title of the change that was made to an API.
Consumer Rights Honored
Require that an API honors the rights of its consumers and the people its data represents, including access, correction, portability, and deletion. As APIs become the infrastructure of public and e...
Data Ownership Respected
Require that an API respects the ownership of the data it handles, treating consumer and end-user data as belonging to them rather than to whoever stores it. Ownership shapes what a provider may do...
Data Residency Enforced
I require that every API declares where the data it handles is stored and processed, and that those residency commitments are actually enforced rather than merely stated in a policy document. Consu...
Data Retention Defined
Require that every API declare a written retention policy stating how long each category of data is kept, why it is kept, and when it is destroyed. I expect this policy to be discoverable alongside...
Dependency SBOM Maintained
Require that every API maintain a current software bill of materials enumerating the libraries, services, and versions it depends on. I want a machine-readable SBOM and dependency manifest kept in ...
Feedback Issues
Allow for teams to receive feedback on API contracts via Git issue.
Feedback
Providing feedback on the business and technical details of each API contract, helping facilitate feedback from consumers and other stakeholders, but also from the learnings across other private an...
API Governance Rules
Spectral rules that apply to the API level, linting OpenAPI.
Compliance Mapping (Governance)
Require that every API in production maps its endpoints, data, and controls to the specific regulatory and compliance obligations it falls under, whether that is GDPR, HIPAA, PCI DSS, SOC 2, or an ...
Dependency Management (Governance)
Require that every API declares the upstream services, libraries, and other APIs it depends on, and keeps that list current as part of its governance record. I care about this because APIs never st...
API Lifecycle
A human and machine-readable schema of the common and agreed upon API lifecycle.
Maturity Scoring (Governance)
Require that every API is scored against a shared maturity model that measures design, documentation, testing, security, and operational readiness, and that the score is visible to the team that ow...
Operational Governance Rules
Spectral rules that apply to the operational level, linting APIs.json.
Governance Policies
Human and machine-readable policies that define an aspect of API operations, which are always kept in alignment with business objectives.
Policy Exceptions (Governance)
Require that any deviation from a governance policy is requested, justified, time-boxed, and approved through a documented exception process rather than quietly ignored. I have learned that rigid r...
Review & Approval (Governance)
Require that every API design and significant change passes through a documented review and approval step before it ships, with clear owners and clear criteria. I am a big believer in design-first ...
Governance Vocabulary
A formal vocabulary of words and phrases that can and cannot be used across operations.
Governance
Governance standardizes APIs across teams using a common platform and lifecycle, applying governance policies and rules, and keeping everyone moving in the same direction using common guidance.
Business Guidance
Provide access to business API guidance as part of API contract support.
People Guidance
Provide access to people API guidance as part of API contract support.
Policy Guidance
Provide access to API policy guidance as part of API contract support.
Technical Guidance
Provide access to technical API guidance as part of API contract support.
Guidance
Ensuring there is guidance for teams throughout their API journey, providing simple text and video guidance for all of the topics business and engineering teams will encounter as part of their regu...
Login for APIs
Providing a way to login and gain access to an API, offering a simple human-readable URL to the login page, or ideally some sort of automated login process that allows access with as few clicks and...
Open Standards Adopted
Require that APIs are defined and delivered using open standards such as OpenAPI, AsyncAPI, and JSON Schema rather than proprietary formats. Open specifications lower the cost of adoption, enable i...
Elements
Offering other elements or features of an API that are included or not included within a plan to help API consumers understand scope of what is available.
Regions
Providing regional details available for access API resources and capabilities in different geographical regions as part of API plan usage.
Time Frame
Break down usage for for consumers based upon second, minutes, days, weeks, months, or other relevant time-frame for them to understand their usage.
Policies
Providing the machine-readable policies that link machine-readable rules with the business reasons why we are governing an API and the operations around it, helping organize rules based upon the bu...
Problem Details for HTTP APIs
Requiring that errors use the Problem Details for HTTP APIs standard.
Certifications
Provide the provenance of an API contract using regular certifications
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.
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...
Questions Issues
Allow for teams to ask questions and get answers via Git Issues.
Questions
Empowering teams to ask questions via issue or discussion via Git repository, or directly via email about the API lifecycle, governance, as well as the business or technical elements of producing a...
Reuse Scoring Applied
Require that every API carry a reuse score that measures how widely and effectively it is being reused across teams and how much it duplicates existing capabilities. I want reuse assessed with a co...
Date
The date for the proposed API change in the road map.
Details
The description for the proposed API change in the road map.
Title
The title for the proposed API change in the road map.
Rules
Providing the machine-readable rules used to govern an API that can be used as part of pipelines or other automation to lint an API, making sure the baseline for each API and the operations around ...
Abuse Prevention (Security)
Require that every API is designed to resist abuse and misuse, so I want throttling, quotas, anomaly detection, bot and scraping defenses, and sensible request limits treated as part of the contrac...
Authorization (Security)
Require that every API defines and enforces authorization explicitly, so I want each operation to declare what scopes, roles, or permissions it demands and to check them on every request, not just ...
CORS (Security)
Require that every browser-facing API sets a deliberate, least-privilege CORS policy, so I want explicit allowed origins, methods, and headers rather than a lazy wildcard slapped on to make an erro...
Data Classification (Security)
Require that every API classifies the data it moves and applies protections that match that classification, so I want fields and payloads labeled as public, internal, confidential, or regulated, wi...
Input Validation (Security)
Require that every API validates all incoming data against its schema before acting on it, so I want types, formats, lengths, ranges, and required fields checked at the edge and anything that does ...
Transport (Security)
Require that every API is served exclusively over encrypted transport, so I want TLS enforced everywhere, plain HTTP either redirected or refused, weak protocols and ciphers disabled, and HSTS in p...
HTTP
The Hyper Text Transfer Protocol (HTTP) from the IETF.
JSON Schema
Using the JSON Schema to define and validate models.
JSON
Using the JavaScript Object Notation (JSON) format.
OpenAPI
Using the OpenAPI specification to describe HTTP APIs.
Spectral
Using the Spectral to define linting rules for APIs.
YAML
Using the Yet Another Markdown Language (YAML) format.
Standards
Internet, industry, market, and government standards help make APIs more consistent, but also save time and money for both producer and consumer, while keeping APIs better aligned with existing ind...
