Design is where the human experience of an API is won or lost. I work design-first, shaping the paths, schema, errors, and naming in the contract before development begins, so that consistency is baked in rather than bolted on. A well-designed API is one a developer can understand without having to ask anyone for help.
Design
Design
Stop 4
Policies at this stop
URL for APIs.json Contracts
Providing the valid URL for the APIs.json contract, identifying the source of the contract which may or may not be where it is found, helping make contract authoritative.
Arazzo Workflows Provided
Require that APIs which chain multiple operations to accomplish real work provide Arazzo workflow definitions describing those sequences. I want the multi-step paths a consumer must follow, the ord...
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 ...
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...
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 ...
Batch Operations (Design)
Require that APIs handling high volumes of records offer explicit batch operations rather than forcing consumers to hammer single-resource endpoints in a loop. Every API must define clear semantics...
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...
Compatibility (Design)
Require that changes to an API preserve backward compatibility by default, and that any deviation is a deliberate, governed decision rather than an accident of a merge. Every API must be designed s...
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....
Hypermedia (Design)
Require that APIs return links alongside their data where it helps consumers navigate related resources, discover available actions, and follow state transitions without hardcoding URLs. APIs shoul...
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 ...
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...
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....
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...
Documentation Paths
Providing simple, clean, and intuitive paths as part of the documentation being published for consumers to use.
Documentation Responses
Making sure there is a complete example for each API response in documentation, including happy and unhappy responses.
Documentation Schema
Documenting all of the schema which are used as part of request bodies and responses, providing JSON SChema representations of each.
Event Types Cataloged
I require that every event an API emits is enumerated in a published catalog of event types, each with a stable name, a described payload, and a clear meaning, so consumers know exactly what can ha...
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. ...
Usage of JSON Path Standard
Using JSON Path to identify properties of a schema.
Centralizing Headers Using Components
Requiring that OpenAPI components headers meet the policy standards.
Centralizing Headers Using Components
Requiring that OpenAPI components headers meet the policy standards.
OpenAPI Components
The OpenAPI Components object enables the centralization of common technical details within an API, promoting modularity and reusability. Using the components object as a standard practice helps re...
Providing External Document References
Requiring that all OpenAPI external documentation meet the policy standards.
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...
Contact Information for APIs
Requiring that there is a contact included in the OpenAPI info.
Description of APIs
Requiring the info description property meets the policy standards.
License for APIs
Requiring the info license property meets the policy standards.
Terms of Service for APIs
Requiring the info terms of service property meets the policy standards.
Title of APIs
Requiring the info title property meets the policy standards.
Version of APIs
Requiring the info version property meets the policy standards.
Description of API Operations
Requiring that all operational descriptions meets the policy standards.
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 ...
Unique Identrifiers for API Operations
Requiring that all operational unique identifiers meets the policy standards.
Parameter Descriptions
Requiring that all operational parameters descriptions meets the policy standards.
Parameter Enumerators
Requiring that all operational parameters enums meets the policy standards.
Parameter In Query or Path
Requiring that all operational parameters in property meets the policy standards.
Parameter Names
Requiring that all operational parameters names meets the policy standards.
Parameter Schema
Requiring that all operational parameters schema meets the policy standards.
Parameter Types
Requiring that all operational parameters type property meets the policy standards.
Parameters
Requiring that all operational parameters meets the policy standards.
Request Bodies Examples
Requiring that all operational request body examples meets the policy standards.
Request Bodies Media Types
Requiring that all operational request body media types meets the policy standards.
Request Bodies Schema
Requiring that all operational request body schema meets the policy standards.
Request Bodies
Requiring that all operational request bodies meets the policy standards.
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 ...
Response 2xx
Requiring that all 2xx responses meets the policy standards.
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 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 ...
Response 4xx
Requiring that all 4xx responses meets the policy standards.
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...
Response 5xx
Requiring that all 5xx responses meets the policy standards.
Operation Security
Requiring that all operational security meets the policy standards.
Operation Summary
Requiring that all operational summaries meets the policy standards.
Operation Tags
Requiring that all operational tags meets the policy standards.
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 Names
Requiring API paths meets the policy standards that are set.
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 Descriptions
Requiring that all schema descriptions meets the policy standards.
Schema Names
Requiring that all schema names meets the policy standards.
Schema Properties
Requiring that all schema properties meets the policy standards.
Schema Property Descriptions
Requiring that all schema property descriptions meets the policy standards.
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 Names
Requiring that all schema property names meets the policy standards.
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 Property Shapes
Requiring that all schema property shapes meets the policy standards.
Schema Property Type
Requiring that all schema property types meets the policy standards.
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...
Schema Type
Requiring that all schema type meets the policy standards.
OpenAPI Security
Requiring that OpenAPI security meet the policy standards.
Servers (OpenAPI)
Require that every OpenAPI definition declares its servers, the concrete base URLs where the API actually lives, ideally with an entry for each environment so production and sandbox are both discov...
OpenAPI Tags
Requiring that all OpenAPI tags meet the policy standards.
OpenAPI Version
Requiring there is the latest version of OpenAPI available.
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 ...
Response Time
Requiring details regarding the regular response time for each available API.
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...
JSON Schema
Using the JSON Schema to define and validate models.
Tool Definitions Provided
I require that APIs publish explicit tool definitions that describe each callable capability as a discrete tool an agent can select, with clear names, descriptions, and typed inputs and outputs. Th...
Webhook Contracts Defined
I require that every webhook an API sends is described by a real contract that specifies its trigger, its payload, its headers, and its delivery and retry behavior, so integrators can build against...
