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 documentation, SDKs, onboarding, error messages, and support, and it is often the single biggest factor in whether an API gets adopted. A great API with a poor developer experience will lose to a mediocre API that is a joy to use. I obsess over developer experience because it is where the technical and the human meet most directly. Developers are consumers with very little patience and very good memories, and they will route around any friction you put in their way. Investing in a smooth, well-documented, predictable developer experience is one of the highest-leverage things any API provider can do.
Developer Experience
Policies
API Mocking (CI/CD)
Require that every API can be mocked directly from its contract so consumers and downstream teams can build against it before the implementation is finished. I lean on mocking because it is what ma...
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...
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...
Interactive Documentation (Experience)
Require that every API ships interactive documentation generated from its contract, where a developer can read the operations, see the schemas, and make a real call right from the page. I have beli...
Localization (Experience)
Require that APIs serving a global audience localize the things developers and end users actually experience, from documentation and portal content to error messages, currencies, and date and time ...
Migration Guides (Experience)
Require that whenever an API version is deprecated or a breaking change is introduced, a clear migration guide is published that shows consumers exactly how to move from the old to the new. I insis...
Sandbox (Experience)
Require that every API offers a sandbox environment with test credentials and safe, representative data so a developer can experiment fully before touching production. I champion sandboxes because ...
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...
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...
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...
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 ...
Support Channels Defined
Require that every API publish clear support channels so consumers know exactly how to get help and what to expect when they ask. I want the path to a human, an issue tracker, or a community forum ...
Strategies
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 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...
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 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 Educate and Enable Consumers
Most of the friction around APIs comes from gaps in understanding, not gaps in technology. I believe API operations have a responsibility to educate and enable the people who use them, through tuto...
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 Invest in Developer Relations
Developer relations is where an API operation puts real people between its technology and its consumers. I want every serious API to have someone whose job is to support developers, gather their fe...
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...
