Consistent communication about the production and consumption of APIs is critical for effective enterprise governance. APIs are inherently difficult to visualize, making it essential to invest in messaging, blog posts, videos, case studies, and other forms of content to enhance their visibility. This communication should cover internal teams, first-party applications, external partnerships, and public third-party developers. Every stage of the API lifecycle offers an opportunity to share updates, tell stories, and keep stakeholders informed. Each API integration presents a chance to shape future versions and inspire new use cases. Communication isn’t just an extra layer of API governance—it’s the driving force behind governance, support, and feedback loops, ensuring API operations continue to evolve and improve.
Communication
Properties
Policies
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 ...
API Outreach and Content
Require that an API is actively communicated through ongoing content and outreach, including blog posts, changelogs, and updates that tell the story of what it does and why it matters. An API launc...
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...
Communication Status Page
Every API must maintain a public status page that reports current health, active incidents, and scheduled maintenance in real time. I require that consumers be able to check the state of an API the...
Community Engagement Channels
Require that an API provides real channels for its community to engage, whether a forum, chat, mailing list, or regular office hours. Consumers need a place to ask questions, share solutions, and c...
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...
Developer Relations Program
Require that any API meant for real adoption is backed by a developer relations function responsible for supporting, advocating for, and growing its community of consumers. Endpoints and documentat...
Documentation
The human-readable HTML, Markdown, or PDF representation of the technical surface area of each API, providing path, methods, summaries, description, examples, and the other resources consumers will...
Localization (Experience)
Require that APIs serving a global audience localize the things developers and end users actually experience, from documentation and portal content to error messages, currencies, and date and time ...
Getting Started
The step by step walk-through for new API consumers, ensuring they have exactly what is needed to discover and onboard, but also help make sure the getting started steps are as simple, plain langua...
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...
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.
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...
Performance
Publishing details regarding the performance of APIs, complimenting status and uptime information, but drilling into more detail regarding speed, latency, and other performance related metrics that...
Plans
Plans are all about being explicit and transparent with all of the access for an API, breaking down the tiers, rate limits, features, and pricing that is available for API consumers, standardizing ...
Portals
Dedicated developer portals for an API provide a way to make documentation, sign-up, getting started, plans, SDKs, and other resources API consumers need more easily accessible publicly or privatel...
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...
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...
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...
Status
Making an API status page, monitoring reports, or other real-time updates regarding the uptime and availability of an API, providing current, but also the historical status of API, helping maintain...
Support Channels Defined
Require that every API publish clear support channels so consumers know exactly how to get help and what to expect when they ask. I want the path to a human, an issue tracker, or a community forum ...
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 ...
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 Contracts Are Validated
All APIs must have a link to the evidence of the contract validation for business and technical contracts, allowing any stakeholder to review the details of the contract, as well as the rules appli...
API Development Is Collaborative Across Teams
API development must be a collaborative effort across product, engineering, and operations teams, with shared workspaces, design reviews, and cross-functional feedback loops that ensure APIs reflec...
API Info and Metadata Is Complete and Accurate
All OpenAPI definitions must have complete info objects including title, description, version, contact information, license, and terms of service, providing both humans and machines with the contex...
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 Responses Must Be Meaningful and Consistent
All API responses should follow Internet, industry, and enterprise standards, providing a meaningful and consistent communication and structure, always providing what was intended for API consumers...
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 Actively Evangelized
An API that nobody knows about might as well not exist. I believe every API operation needs someone actively evangelizing its work, telling the story of what the APIs do and why they matter to the ...
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 Always High Quality and Reliable
All APIs should be high quality and reliable, providing adequate levels of monitoring of its availability and performance, with the proper provenance and communication with producer and consumers r...
APIs Are Always Well Documented
All APIs must have human-readable documentation that defines the technical surface area of each API being made available to API consumers, providing a simple, intuitive, and ideally interactive HTM...
APIs are Defined as API Contracts
All APIs are defined as API contracts so that we can align both the business and technology of delivering consistent high quality APIs, employing source control to manage the technical, but also th...
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 Legally Covered
All APIs must be reviewed by legal council and posses terms of service, privacy policy, licensing, and other regulatory and compliance requirements, making sure all the legal bases are covered bef...
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 Build and Nurture Community
The strongest APIs have communities, not just users. I want API operations to deliberately build the forums, channels, and gatherings where consumers can connect with the provider and with each oth...
APIs Earn and Maintain Consumer Trust
All APIs must demonstrate trustworthiness through transparent service level commitments, consistent deprecation policies, reliable performance, proper security, and clear legal terms, building the ...
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 Must Reusable Whenever Possible
The components of any API should be made modular and reusable whenever it makes sense to the business use case, keeping schema, parameters, examples, error responses, and other common parts of an A...
APIs Operations Possess Dedicated Workspaces
API operations should provide dedicated workspace for domains, lines of business, and teams who are producing APIs, providing a dedicated location where work, collaboration, and automation can occu...
APIs Possess Informative Metadata
All APIs possess metadata that is relevant to what APIs do, but also how they can be used in business by API consumers, and metadata helps ensure that the front door for API operations within this ...
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...
Data Should Be Well-Defined and Validated
The schema for data that is sent and received via API should always be well-defined, possess a well-known shape, and always be validated, ensuring that digital resources and capabilities are what t...
Onboarding is Always as Easy as Possible
API operations is made easier by making common elements like documentation, authentication, SDKs easy to find and available as just a couple of simple steps that API consumers can follow when it co...
Operations Must Always Be Secure
Individual API operations should always be properly secured during design, develop, and run-time, making sure data, credentials, logs, and all other related resources are properly secured and opera...
Operations Must Be Useful and Consistent
All individual API operations must be useful and follow consistent Internet, industry, and enterprise standards, providing a simple and relevant HTTP API operation that does one thing and does it w...
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...
