Principles of Good API Design
An API is a contract between systems. When you design an API, you're making promises about how your service behaves. Good API design makes those promises clear, consistent, and easy to understand. Developers should be able to guess how your API works — and be right.
Core Design Principles
Consistency: Use the same patterns throughout your API. If one endpoint uses createdAt for timestamps, don't use created_at elsewhere. Consistency reduces cognitive load and prevents mistakes.
Predictability: Developers should correctly guess how unfamiliar endpoints work based on patterns they've seen. If GET /users returns a list, GET /products should too.
Simplicity: Make easy things easy and hard things possible. Common operations should require minimal effort. Advanced features can exist but shouldn't complicate basic usage.
Evolvability: Design for change. APIs that can't evolve without breaking clients become maintenance nightmares.
REST Conventions
REST provides a standard vocabulary that most developers understand:
GET /users → List all users
POST /users → Create a new user
GET /users/123 → Get user with ID 123
PUT /users/123 → Replace user 123 entirely
PATCH /users/123 → Update specific fields of user 123
DELETE /users/123 → Delete user 123
These conventions are so widespread that deviating from them confuses developers. Use HTTP methods as intended — GET for reading, POST for creating, PUT/PATCH for updating, DELETE for removing.
Naming Conventions
Use nouns, not verbs: Resources are things, not actions.
Good: GET /users
Bad: GET /getUsers
Good: POST /orders
Bad: POST /createOrder
Use plural nouns: Collections should be plural for consistency.
Good: /users, /products, /orders
Bad: /user, /product, /order
Use lowercase with hyphens: This is the most readable and URL-friendly format.
Good: /user-profiles
Bad: /userProfiles, /user_profiles
Nested Resources
Express relationships through URL structure:
GET /users/123/orders → Orders for user 123
GET /orders/456/items → Items in order 456
But don't nest too deeply — /users/123/orders/456/items/789/details becomes unwieldy. Two levels is usually the maximum.