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 them across all APIs within the organization.
APIs Follow Consistent Design Patterns
Policies
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...
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...
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...
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...
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....
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...
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...
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...
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 ...
Path Names
Requiring API paths meets the policy standards that are set.
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...
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 ...
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 ...
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...
Experiences
Consistency
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 var...
Quality
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 exp...
Onboarding
Transitioning from API discovery to integration as a consumer requires a well-defined and streamlined API onboarding process. Onboarding begins with discovery and relies heavily on clear documentat...
Developer Experience
Developer experience is the sum of every interaction a developer has with an API, from the first time they land on the portal to the hundredth time they call an endpoint in production. It covers do...
Simplicity
Simplicity is a hallmark of well-designed HTTP APIs, but achieving simplicity requires effort. The likelihood that a partner or third-party developer will abandon an API increases as cognitive load...
Interoperability
Interoperability is the experience of APIs, systems, and data working together without heroic effort. It is built on shared standards, common schema, and predictable contracts that let one system t...
