APIs are contracts between your code and external code. A bad API contract means every change breaks clients. A good API contract means you can improve your implementation without affecting users.
The difference is design discipline.
Make the common case easy
Most APIs fail because they optimize for the 10% case and make the 90% case painful.
Example: An API that requires 5 parameters always, but only 2 of them are common. Clients write:
POST /api/resource
{
"requiredParam1": "value",
"requiredParam2": "value",
"optionalParam3": null,
"optionalParam4": null,
"optionalParam5": null
}
Better design: Make common parameters required, optional parameters truly optional.
POST /api/resource
{
"id": "123",
"name": "example"
// param3, param4, param5 are optional
}
The principle: friction in API design is friction in client code. Good API design removes friction from common operations.
Versioning is about stability, not features
Many APIs fail because they version to add features. This creates API v1, v2, v3, each with different semantics. Clients are confused. The API team maintains three versions.
Better approach: A stable API interface (v1) with features that are backward compatible. Add fields that might be ignored. Deprecate fields that are no longer used.
Versioning should be for breaking changes only: changing the semantics of existing fields, removing endpoints, restructuring responses.
Design for discoverability
Good APIs let developers discover capabilities without reading documentation.
Practices:
- Consistent naming: If an endpoint is
/users, the related one should be/users/{id}, not/user/{id}or something else. - Consistent structure: Error responses should always look the same. Success responses should have a consistent structure.
- HATEOAS (links): Include related URLs in responses so clients can discover what they can do next.
- Clear semantics: HTTP verbs should mean what they usually mean (GET for retrieval, POST for creation, etc.)
When every endpoint is surprising, documentation becomes a requirement, not a convenience.
Errors should be informative
A common failure: API returns 400 Bad Request without explaining which parameter was bad or why.
Good error responses tell you:
- What went wrong specifically (which parameter, which validation rule)
- How to fix it (suggestion for the correct format)
- What to do next (can you retry, or is it a permanent failure)
Example:
{
"error": {
"code": "INVALID_AMOUNT",
"message": "Amount must be positive and at most 2 decimal places",
"field": "amount",
"suggestion": "Did you mean 10.50?"
}
}
Versus:
{
"error": "Bad Request"
}
The difference is huge for client developers.
Think in terms of resources, not operations
Weak API design thinks in operations: "CreateUser", "UpdateUser", "DeleteUser". This creates an endless list of endpoints.
Resource-based design is simpler: You have Users (a resource). You can GET, POST, DELETE them. The operation is implied by the HTTP verb and the URL.
GET /users # List users
POST /users # Create user
GET /users/123 # Get specific user
PATCH /users/123 # Modify user
DELETE /users/123 # Delete user
This is simpler than:
POST /api/create-user
POST /api/update-user
POST /api/delete-user
GET /api/list-users
GET /api/get-user
Resources are easier to understand, easier to document, and easier to implement consistently.
Make backward compatibility automatic
APIs break when you make changes that existing clients don't expect. Smart API design makes many changes backward compatible:
Adding fields: Existing clients ignore new fields, so this is safe.
Adding query parameters: Mark them as optional, so existing clients that don't send them still work.
Adding HTTP headers: Clients ignore headers they don't expect, so this is safe.
Deprecating fields: Support old field names while encouraging the new name.
Breaking changes (require versioning):
- Removing endpoints
- Changing response structure (not adding to it, but changing what's there)
- Changing semantics of existing parameters
- Changing error responses
The principle: changes to the API are backward compatible unless they require a version bump.
Test your API with different versions of clients
A testing practice that catches API problems early: Write client code that depends on your API, and test that code with different API versions.
This surfaces problems:
- Client code assumes something about the API that isn't documented
- Changes to the API that you think are backward compatible actually break clients
- Error cases that clients don't handle
For a production API, testing backward compatibility is as important as testing the API itself.
Documentation reflects design quality
Good APIs need less documentation because the interface is self-explanatory. Bad APIs need extensive documentation because every endpoint is surprising.
Your documentation should show:
- Common use cases (the 90% case should be obvious)
- Example requests and responses
- Error cases
- Rate limits and quotas
If your documentation is 50 pages for a simple operation, your API design has problems.
The best APIs are the ones that developers can figure out by trying them, then consult documentation only for the details.