I've consumed more APIs than I care to count. Some were a joy to work with. Others made me question my career choices. Here are five lessons I've internalised from both sides of that experience.
1. Version from day one
The moment you ship a public API, you've made a contract with your consumers. Breaking changes are inevitable — requirements change, you discover design mistakes, you rename things. Without versioning, every breaking change breaks every consumer simultaneously. With versioning (/v1/, /v2/), you can evolve the API while giving consumers time to migrate.
2. Consistent error shapes
Nothing wastes more time than an API that returns { error: "bad" } for one endpoint and { message: "Something went wrong", code: 500 } for another. Pick a shape and stick to it across every endpoint:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Email is required",
"field": "email"
}
}3. Don't invent your own auth
Use OAuth 2.0, API keys, or JWTs — patterns developers already understand. Every custom auth scheme I've encountered has had security holes that took months to surface.
4. Pagination is not optional
Returning all 50,000 records in one response will eventually take down your server and timeout every client. Implement cursor-based pagination from the start. Retrofitting it later is painful.
5. Document the unhappy path
Most API docs show the success response. Few document what happens when things go wrong. List every error code, what triggers it, and what the caller should do. This is the documentation your users actually need at 2am when something breaks.