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 experiences—for developers onboarding and integrating with APIs, as well as for end-users relying on applications powered by those APIs. API quality impacts business operations in numerous ways, making it a critical factor for success. Testing, monitoring, tracing, and observability all play a vital role in improving API quality. However, the design and broader operational properties of APIs also influence the overall quality discussion. HTTP APIs should be simple, effective, and focused on doing one thing reliably well. While tactical improvements can enhance the API experience incrementally, achieving higher levels of quality requires addressing strategic challenges across the API lifecycle.
Quality
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.
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...
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 ...
Linting (CI/CD)
Require that every API contract is automatically linted against our design and governance rules on each commit, so standards are enforced by machines rather than by memory and goodwill. I love lint...
Best Practices (Design)
Require that every API adheres to the shared design best practices we have codified across the platform, so that consistency is a default and not something each team reinvents. Every API must refle...
Data Types (Design)
Require that every property in an API contract declares an explicit, well-chosen data type with the right format, precision, and constraints instead of leaning on loose strings and hopeful parsing....
Validation (Design)
Require that every API defines and enforces validation rules in its contract, using schemas, constraints, required fields, and formats so that bad input is rejected with a clear, consistent error i...
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...
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...
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
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.
2xx Response Schema (OpenAPI)
Require that every 2xx response defines a schema for its body, describing the exact shape, properties, and types a consumer will receive on success rather than handing back an undocumented blob. I ...
Schema Constraints (OpenAPI)
Require that our schemas express real constraints on their properties, the minLength and maxLength, minimum and maximum, patterns, and formats that describe what valid data actually is rather than ...
Schema Property Enums (OpenAPI)
Require that any property with a fixed set of allowed values declares those values as an enum in the schema, so status, type, and category fields cannot drift into a free-for-all of typos and inven...
Schema Property Required (OpenAPI)
Require that our schemas explicitly list which properties are required, so consumers know which fields they can always count on and which ones may be absent. I have written code that trusted a fiel...
Schema Required (OpenAPI)
Require that every request and response body in our OpenAPI definitions references a defined schema rather than accepting or returning free-form, untyped content. I have run into operations that de...
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...
Privacy Policy
Publishing a privacy policy covering the producer and consumers of an API, as well as end-users of applications, adding to the legal resources that are available to 3rd party developers when puttin...
Procurement Evaluation Checklist
Require that every API considered for adoption be run through a documented procurement evaluation checklist before a team commits to it. I want the same questions asked each time, covering security...
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...
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 ...
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...
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
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 ...
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 ...
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 Delivery Is Fast and Design-First
API delivery must follow a design-first approach with mock servers, contract testing, and schema registries that enable parallel development, allowing consumers to begin integration before implemen...
API Errors Are Standardized and Informative
All API error responses must follow standardized formats like RFC 7807 Problem Details, providing consistent error codes, human-readable messages, and correlation IDs that enable consumers to progr...
API Governance Is Automated in CI/CD
All API governance checks including linting, contract testing, and schema validation must be automated within the CI/CD pipeline, ensuring that governance is enforced consistently at build time rat...
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 Maturity Is Measured and Improved
All APIs must be assessed against a maturity model that measures documentation, security, testing, monitoring, and consumer experience, providing a measurable way to track progress, compare APIs, a...
API Parameters Are Well-Defined and Consistent
All API parameters must have clear names, descriptions, types, and constraints following consistent casing and naming conventions, with reusable parameters centralized in OpenAPI components to redu...
API Provenance Is Maintained and Auditable
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, audita...
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...
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 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 Evaluated Before Adoption
I want us to evaluate an API before we build on it, because the cheapest time to discover a bad dependency is before it is wired into production. That means running third-party APIs through a procu...
APIs Are Interoperable Across Systems
All APIs must prioritize interoperability by using standard media types, hypermedia link relations, and well-known specifications, enabling consumers to integrate multiple APIs together and reducin...
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 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 Observable and Monitored
All APIs must have comprehensive observability including monitoring, logging, health checks, and alerting, with defined SLIs and SLOs that ensure teams can proactively detect, diagnose, and resolve...
APIs Deliver an Exceptional Developer Experience
All APIs must prioritize the developer experience by providing interactive documentation, sandbox environments, realistic examples, and intuitive naming, ensuring that developers can quickly unders...
APIs Follow Consistent Design Patterns
All APIs must follow consistent design patterns for naming conventions, media types, pagination, filtering, sorting, and error handling, ensuring that consumers can learn patterns once and apply th...
APIs Have Clear Service Level Commitments
All production APIs must have defined service level agreements (SLAs) that specify uptime, availability, latency, and throughput commitments for each plan tier, providing consumers with the confide...
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 Scale Efficiently Under Load
All APIs must be designed to scale efficiently as consumer traffic and data volumes grow, employing caching, pagination, filtering, and batch operations to ensure consistent performance and avoid d...
APIs Support Event-Driven and Asynchronous Patterns
APIs that require event-driven or asynchronous communication must follow consistent standards for webhook registration, payload formats, retry policies, and delivery guarantees, enabling reliable a...
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...
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...
