Achieving consistency in the design, delivery, and maintenance of HTTP APIs across an enterprise is a significant challenge—one that often complicates API operations. Small differences, such as variations in HTTP status codes or authentication methods, can lead to added costs and delays during integration. However, this also presents an opportunity to introduce incremental changes at scale, making APIs more consistent and easier to manage. Consistency can mean different things to different teams, which is why a policy- and rule-driven approach is essential for defining, prioritizing, and evolving standards. These policies and rules can be adopted flexibly across domains and teams, aligning with broader business and governance objectives. The goal isn’t to enforce 100% uniformity but to establish a clear and consistent framework for common patterns and practices, while addressing anti-patterns in HTTP API delivery.
Consistency
Properties
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...
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...
Schema Registry (CI/CD)
Require that the schemas an API relies on are published to a shared schema registry and validated against it in CI/CD, so the shapes of our data are versioned, discoverable, and compatible. I want ...
Deployment Environments Defined
Every API must define its deployment environments explicitly, naming where it runs across development, staging, and production and how consumers reach each one. I require that base URLs, credential...
API First (Design)
Require that every API begins with a design-first contract, an OpenAPI definition authored and agreed upon before a single line of implementation code is written. I have watched too many teams code...
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....
Idempotency (Design)
Require that state-changing operations be safe to retry, either because the method is inherently idempotent or because the API supports an idempotency key that lets a consumer replay a request with...
Media Types (Design)
Require that every request and response declares an accurate, standard media type, and that content negotiation is handled deliberately rather than assumed to always be JSON. Every API must be expl...
Naming Conventions (Design)
Require that every API follows a single, documented set of naming conventions for resources, fields, parameters, and enums, so a developer who learns one of our APIs already understands the next. E...
URL Structure (Design)
Require that every API uses a consistent, predictable URL structure, with clear resource hierarchies, sensible pluralization, and paths that read like the nouns of the domain rather than a grab bag...
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...
DNS Is Managed
Require that the DNS behind every API be deliberately managed, with ownership, records, and TTLs tracked as part of the API's operational contract. I expect hostnames to be stable, certificates to ...
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...
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 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.
GraphQL Schema Governed
I require that any GraphQL API ships a published, versioned schema that we govern like any other contract, with consistent naming, deliberate types, and a clear boundary on what the graph exposes. ...
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...
HTTP Methods (OpenAPI)
Require that every operation in an OpenAPI definition uses the correct HTTP method for the action it performs, GET to read, POST to create, PUT and PATCH to update, DELETE to remove, and that we do...
HTTP Status Codes (OpenAPI)
Require that every operation documents the HTTP status codes it can actually return, using the standard families the way the web intends, 2xx for success, 3xx for redirection, 4xx for consumer mist...
Operation ID Conventions (OpenAPI)
Require that every operation in our OpenAPI definitions carries a unique, human-readable operationId that follows a consistent naming convention across the whole surface, something like getUser or ...
2xx Response Examples (OpenAPI)
Require that every successful 2xx response in our OpenAPI definitions includes at least one realistic example, so a consumer can see exactly what a good answer looks like without making a live call...
2xx Response Media Types (OpenAPI)
Require that every 2xx response declares the media types it returns, spelling out application/json or whatever content it actually serves rather than leaving the content negotiation a mystery. I ha...
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 ...
4xx Response Media Types (OpenAPI)
Require that every 4xx client-error response declares its media type, so consumers know whether an error comes back as application/json, application/problem+json, or something else entirely. I have...
4xx Response Schema (OpenAPI)
Require that our 4xx client-error responses define a schema, ideally a consistent error object with a code, a message, and enough detail for a consumer to understand what went wrong and how to fix ...
OpenAPI Overlays Used
Require that consistent, cross-cutting changes to OpenAPI definitions be applied through OpenAPI Overlays rather than by hand-editing each specification. I want shared conventions, added examples, ...
Path Trailing Slashes (OpenAPI)
Require that our OpenAPI paths follow one consistent rule about trailing slashes, and I strongly prefer no trailing slash so that /orders and /orders/ never become two subtly different things. I ha...
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...
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 ...
Operations Are Agent-Legible
I require that every operation in an OpenAPI carries a description rich enough that an agent can decide, from the definition alone, what the operation does, when to call it, and what it will get ba...
Error Handling (Operations)
Require that every API returns standardized, informative errors, so I want a consistent error envelope, a correct HTTP status code, a machine-readable code, and a human-readable message on every fa...
Filtering & Sorting (Operations)
Require that collection endpoints offer consistent, documented filtering and sorting, so I want a shared convention for query parameters, allowed fields, operators, and sort order applied the same ...
Pagination (Operations)
Require that every endpoint returning a collection paginates its results using a single, consistent strategy, so I want a documented approach, whether cursor or offset, with clear page-size limits ...
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 ...
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 ...
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 Authentication Is Standardized
All APIs must use standardized authentication mechanisms including OAuth, JWT, and API keys with properly defined scopes, ensuring that security is consistently implemented and that consumers have ...
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 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 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 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 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 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 Deployed Consistently and Automatically
I want every API to reach production the same way, through automation, rather than through whatever manual steps a given team happened to invent. That means deployments are automated so a release i...
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 Legible to Automated Consumers
I want our APIs to be legible to the automated consumers reading them, not just to the humans who wrote them. That means operations that describe themselves clearly, tool definitions that spell out...
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 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 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 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...
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...
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...
