If an API isn’t reliable, consumers will eventually look for alternatives. Reliability starts with the platform and infrastructure where the API is deployed, but it also depends heavily on the pace of change and the communication surrounding those changes. At its core, API reliability is more about trust than technical specifications, and each API producer may define reliability slightly differently. A clear understanding of how consumers use an API in their applications can greatly influence what reliability means in practice. While reliability often comes down to uptime and availability, it can also include perceived performance and the quality of digital resources and capabilities. Reliability is built over time, as trust with consumers grows and careful decisions are made to guide the API’s evolution.
Reliability
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.
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...
Async Webhooks (Design)
Require that any API delivering events to consumers describes its webhooks as first-class citizens in the contract, using the OpenAPI webhooks object to define the payloads, headers, and callbacks ...
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...
Long Running Operations (Design)
Require that operations which cannot complete within a normal request window be modeled explicitly as asynchronous, long-running jobs rather than being forced into a single blocking call that ties ...
Robustness (Design)
Require that APIs are designed for robustness on both sides of the wire, being conservative in what they send and tolerant in what they accept, so that small variations do not cascade into outages....
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 ...
SLA (Experience)
Require that every API published for consumers carries a clear service level agreement stating its uptime target, expected performance, support commitments, and what happens when we fall short. I p...
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...
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...
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.
Observability Is Instrumented
Every API must be instrumented for observability, exposing metrics, traces, and health signals that let operators understand its behavior in real time. I require that latency, error rates, and thro...
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...
4xx Response Examples (OpenAPI)
Require that our 4xx client-error responses carry real examples, so a developer can see exactly what a validation failure, an unauthorized call, or a missing resource actually returns. I have spent...
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 ...
5xx Response Media Types (OpenAPI)
Require that every 5xx server-error response declares its media type, so that even when our own infrastructure fails, consumers still receive a predictable, parseable body instead of whatever a pro...
5xx Response Schema (OpenAPI)
Require that our 5xx server-error responses define a schema, reusing the same standardized error object we use elsewhere so a consumer can handle our failures the same way they handle everything el...
Caching (Operations)
Require that every read-heavy API sets explicit HTTP caching headers, so I want Cache-Control, ETag, and Last-Modified in play with sensible max-age and validation behavior spelled out in the contr...
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...
Health Checks (Operations)
Require that every API exposes a standard health check endpoint, so I want a predictable path that reports liveness and readiness along with the status of critical dependencies. I insist on this be...
Monitoring (Operations)
Require that every API is actively monitored for availability, latency, error rates, and traffic, so I want the golden signals collected, dashboarded, and wired to alerts before an API ever reaches...
Rate Limiting (Operations)
Require that every API enforces rate limits and communicates them clearly, so I want defined quotas per consumer, standard headers that report remaining budget, and a proper 429 with a Retry-After ...
Performance Budgets Defined
Require that every API define performance budgets, setting explicit targets for latency, throughput, and error rates that it commits to holding. I expect these budgets to be measured continuously a...
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...
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...
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...
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...
SLA Defined and Published
I require that every production API defines a service level agreement and publishes it where consumers can find it, stating the availability, performance, and support commitments we are willing to ...
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 Authorization Is Properly Defined and Enforced
All APIs must have clearly defined authorization models that control what authenticated consumers can access and perform, using role-based or attribute-based access control to ensure that permissio...
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 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 Dependencies Have an SBOM
I want a software bill of materials for the APIs and services we depend on, so that we always know what is actually in the systems we ship. Every external API we consume is a dependency, and if we ...
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 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 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 Observable Across Operations
I want to be able to see what our APIs are doing in production, because an API we cannot observe is an API we cannot actually operate. That means standardized logging so every service tells its sto...
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 Are Protected from Abuse and Misuse
All APIs must have abuse prevention mechanisms beyond basic rate limiting, including throttling, quotas, circuit breakers, and bot detection, ensuring the stability and availability of APIs for leg...
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 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...
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...
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...
