Managing and effectively communicating changes across one or more APIs is a leading cause of instability and friction in enterprise operations. While these changes often surface in applications used by end-users, the root cause is frequently minor or breaking updates that could be mitigated through versioning, testing, and machine-readable artifacts—validated using JSON Schema during design or runtime. Change is inevitable in enterprise environments, but the real challenge lies in the lack of visibility and communication surrounding it. Issues often arise not from the changes themselves, but from their sudden, unannounced implementation. Effective API change management starts with source control and CI/CD pipelines and extends to consistent strategies for notifying stakeholders about both minor and major updates.
Change
Policies
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.
Blog Feeds
A blog RSS or Atom feed provides a simple way to syndicate information and updates about APIs with producers and consumers, allowing it to be pushed out to where they are located and regularly cons...
Blogs
A blog helps provide a regular channel for publishing relevant stories and information for both producers and consumers of an API, providing a simple, informative, and recurring way to stay in enga...
Change Log
Having a change log of anything added, updated, or removed for an API, but also for the other operational and supporting resources for each API, ensuring there is a easy to read manifest of what ha...
Deprecation Sunset Headers
Every deprecated API operation must announce itself in-band using Deprecation and Sunset headers that tell consumers a change is coming and when it lands. I require that deprecation be signaled thr...
Migration Guides (Experience)
Require that whenever an API version is deprecated or a breaking change is introduced, a clear migration guide is published that shows consumers exactly how to move from the old to the new. I insis...
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...
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.
API Licensing
Publishing a license for the interface, client code, server code, and data to ensure consumers understand the legal implications of using the API, code, and data into their own applications and int...
Breaking Changes (Lifecycle)
Require that breaking changes to a production API are identified, avoided where possible, and never shipped silently onto an existing version. I hold this line hard because a breaking change you di...
Change Management (Lifecycle)
Require that every change to a production API moves through a defined change management process that assesses impact, tracks dependencies, and communicates what is changing before it lands. I want ...
Deprecation (Lifecycle)
Require that any API or operation being retired is formally deprecated first, marked in the contract, and announced with a clear sunset date and migration guidance. I treat deprecation as a promise...
Retirement (Lifecycle)
Require that retiring an API is a deliberate, documented step that only happens after a deprecation period, with the shutdown date, the reason, and the alternative all made clear to consumers. I wa...
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
Road Map
Providing a simple yet informative look at what features are being planned for future releases of an API, or even sharing that nothing is currently being planned--just providing any insight on what...
SDKs
Offering software development kits, or SDKs for an API, handling authentication, and working across all available API operations in a variety of relevant programming languages to the targeted consu...
Security
Providing an overview of security practices for an API, including details covered as part of authentication and access management, but also security testing and certifications that matter to API co...
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...
Support
Outline what support is available for API consumers, including email, tickets, forums, and paid support services, making it easy for API consumers to understand how they can get the help they need ...
Terms of Service
Making sure that terms of service are front and center for API consumers, ensuring that the legal side of using API resources and capabilities in applications and integrations by 3rd party consumer...
Use Cases
The who, what, how, and why of producing an API, making sure all of the known use cases are accurately described and kept up to date, then used to ensure each API is delivering what is expected wit...
Versioning
Providing semantic or date-based versioning for an API, offering an overview of what is adopted for an API and why, letting consumers know that their is change management in place and how they can ...
Videos
Videos offer an engaging way to provide information and updates with producers nad consumers of APIs, demonstrating how an API can be used, providing webinars, workshops, and other useful videos ab...
Strategies
API Change is Managed Relative to Operational Change
Individual APIs should be aligned with overall operational change, providing a common operational change log and road-map that is higher level than change for each individual API, but provides a co...
API Dependencies Are Tracked and Managed
All API-to-API dependencies must be documented and tracked, with upstream and downstream impact analysis performed before changes are made, ensuring that teams understand the ripple effects of chan...
API Paths Must Conform to the Organization
All API paths must conform to the overall organizational domain standards, utilizing plain language and a resourceful approach to delivering digital resources and capabilities via HTTP APIs, provid...
API Versioning Follows a Defined Standard
All APIs must follow a defined versioning strategy, whether semantic versioning or date-based versioning, with clear policies for how versions are communicated, how consumers are migrated, and how ...
APIs Always Have Well-Defined Owners and Stakeholders
Each API should ideally have a dedicated product as well as an engineering owner, with other stakeholders across the API lifecycle defined in an easy to access human readable location, but also def...
APIs Are Aligned with Industry Using Standards
All APIs must be using relevant Internet, industry, and government standards available, ensuring to properly research areas of operations to see what existing standards may exist before the creatio...
APIs Are Always Aligned with the Wider Enterprise
All API contracts must have use cases that align the business reasons why an API is being delivered to consumers with the actual technical details of each API contract, ensuring that operations all...
APIs are Defined by Technical Contracts
All APIs must have machine-readable artifacts that defines the technical surface area of each API being made available to API consumers, utilizing open-source community specifications like OpenAPI ...
APIs Are Gracefully Deprecated and Retired
All APIs must follow a formal deprecation and retirement process that provides consumers with adequate notice, migration support, and a clear timeline from deprecation to removal, ensuring that no ...
APIs Are Made Available Through a Platform Gateway
All APIs must be deployed through a common platform gateway established for the domain, line of business, or team, leveraging development, staging, and production environments, and a common set of ...
APIs Are Part of Regular Active Communication
All APIs are considered and included as part of regular internal and external communication channels, sharing road maps, change logs, blog posts, videos, and other relevant information that produce...
APIs Must Be Actively Governed
All APIs being produced must be governed as part of the overall strategy, using the platform, as well as a common API lifecycle, applying policies and rules, and keeping teams moving in the same di...
APIs Must Be Supported and Have Feedback Loops
All APIs must have support mechanisms to ensure API consumers have self-service or direct support channels, as well as regular feedback loops for soliciting feedback or answering specific API quest...
APIs Work Across Multiple Programming Languages
All APIs should have SDK and other client or server code available in multiple programming languages used by targeted API consumers for known business use cases, making it as simple as possible for...
Breaking Changes Are Prevented or Carefully Managed
All changes to APIs must be evaluated for breaking impact before release, with breaking changes requiring explicit approval, version increments, migration guides, and proactive consumer communicati...
Change is Actively Managed for Each API
All APIs must have change management baked into the definition, delivery, and iteration, ensuring that producers and consumers are in alignment regarding the communication, quality, and velocity of...
Producing APIs MUST Be Repeatable
All APIs must have a single source of truth for all artifacts, as well as the conversations and always be able to be delivered using a repeatable process, leveraging existing software development i...
