API Design Best Practices: What Separates Good APIs from Great Ones
API design is product design. The decisions you make about resource structure, authentication, error handling, and versioning have long-term consequences.
An API is a product. Its users are developers. Like any product, its quality is determined by whether it helps users accomplish what they’re trying to accomplish, with minimal friction.
Resource Design
Use nouns, not verbs: /users, not /getUsers. HTTP verbs (GET, POST, PUT, DELETE) provide the action; the path should describe the resource.
Hierarchical relationships: /users/{id}/orders clearly expresses that orders belong to a user. Keep nesting shallow — more than two levels usually indicates a resource design problem.
Plural consistently: Pick plural or singular for resource names and stay consistent. Plural (/users, /orders) is the more common convention.
Error Handling
This is where most APIs disappoint. Good error responses include a clear error code (machine-readable), a human-readable message explaining what went wrong, and guidance on how to fix it.
Compare: {"error": "400"} vs {"error": {"code": "INVALID_EMAIL", "message": "The email address is not valid. Email addresses must include a domain.", "docs": "https://api.example.com/docs/errors#INVALID_EMAIL"}}. The second response costs the developer seconds to understand and fix. The first costs 15 minutes.
Versioning Strategy
URI versioning (/v1/users) is the most common and most visible. Whatever you choose: version from day one, document what changed between versions, maintain at least one previous version while deprecating, and give developers at least 6 months notice before removing a version.
The Authentication Decision
OAuth 2.0 + JWT for user-delegated access, API keys for service-to-service. Don’t roll your own authentication scheme. Don’t put API keys in URLs — they end up in logs.
