The API That Nobody Wants to Integrate
Every developer who’s integrated a poorly designed API has the same experience: the documentation that describes what the API does without explaining how to actually call it, the error messages that say ‘invalid request’ without specifying what was invalid, the authentication system that requires reading six separate pages to implement, and the response format that buries the relevant data three levels of nesting deep. The poorly designed API costs developers hours of frustrated troubleshooting that a well-designed one would have cost minutes.
API design is a discipline that has well-established best practices, but those practices are inconsistently applied across the software industry. Understanding what makes an API good from the perspective of the developers who’ll use it — developer experience (DX) — produces APIs that are adopted more readily, require less support, and generate more goodwill for the team that built them.
Consistency: The Foundation of a Usable API
Consistency is the most important quality in API design because inconsistency is the primary source of cognitive load for developers integrating APIs. An API where some endpoints use camelCase for field names, others use snake_case, and others use PascalCase requires the developer to remember which convention applies to which endpoint. An API where some endpoints return errors as JSON and others return error HTML requires different error handling code for different endpoints.
The consistency requirements that matter most: consistent naming conventions throughout (pick one: camelCase, snake_case, or any other convention, and apply it everywhere), consistent response structure (similar types of resources should have similar shapes), consistent error format (all errors return the same structure with status code, error code, and human-readable message), and consistent behavior (pagination works the same way across all paginated endpoints; filtering uses the same syntax across all filterable resources).
Error Messages That Actually Help
The error response that most developers receive from poorly designed APIs looks something like: HTTP 400, body: ‘{“error”: “Bad request”}’. This response correctly identifies that the request was bad; it provides no information about what was bad about it, what was expected, or what the developer should change. The developer must guess, read documentation (if it exists and is accurate), and trial-and-error their way to a working request.
A helpful error response provides: the HTTP status code appropriate to the error type (400 for client error, 401 for auth error, 404 for not found, 422 for validation error, 500 for server error), an error code (a machine-readable constant like ‘INVALID_EMAIL_FORMAT’ or ‘MISSING_REQUIRED_FIELD’), a human-readable message that describes what was wrong, and where applicable, a pointer to the specific field or parameter that caused the error and what the expected format or value is. This level of error detail turns a 10-minute debugging session into a 10-second fix.
Documentation That Enables Without Explaining
The best API documentation provides working examples before full specification — developers want to make a call and see what happens before reading every endpoint’s full parameter list. The Stripe API documentation, consistently cited as the best in the industry, leads every endpoint with a code example in the developer’s preferred language, followed by the complete reference. Developers can copy the example, make it work, and then read the full specification to understand the options they haven’t explored yet.
Documentation requirements for a genuinely developer-friendly API: an authentication quickstart that produces a working authenticated call in under 5 minutes, working code examples in the most popular languages for each endpoint, an interactive API explorer where developers can make real calls from the documentation (Swagger UI, Redoc with API playground), clear explanation of error codes with examples of what causes each, and a changelog that documents breaking changes with migration guidance.
Versioning: Planning for Change
APIs change — new features are added, old behavior is improved, mistakes are corrected. How these changes are communicated to and managed for existing API consumers determines whether API evolution is disruptive or graceful. API versioning (including the version in the URL path like /v1/users or in an HTTP header) allows introducing breaking changes in a new version while existing consumers remain on the previous version without disruption.
The versioning practices that prevent disruption: never make breaking changes to an existing version (changes that break existing clients must go into a new version), support previous versions for a defined period with advance notice of deprecation timeline, add new fields rather than changing existing field types or names (additive changes are generally non-breaking), and document every change in a versioned changelog that existing consumers can monitor. The ‘just update everything to the new version’ approach that some APIs take creates integration work for every consumer on every release — the opposite of developer-friendly.