Good API Design = Happy Developers

A well-designed API is a product. Your consumers (other developers) will judge your service by how pleasant your API is to use.

The 12 Rules

1. Use Nouns, Not Verbs

✅ GET /users/123
❌ GET /getUser?id=123

✅ POST /orders
❌ POST /createOrder

2. Use Plural Resource Names

✅ /users, /products, /orders
❌ /user, /product, /order

3. HTTP Methods Have Meaning

Method Action Idempotent
GET Read Yes
POST Create No
PUT Replace Yes
PATCH Update partial Yes
DELETE Remove Yes

4. Use Proper Status Codes

200 OK — Success
201 Created — Resource created
204 No Content — Deleted successfully
400 Bad Request — Client error (validation)
401 Unauthorized — Not authenticated
403 Forbidden — Authenticated but not allowed
404 Not Found — Resource doesn't exist
409 Conflict — Duplicate resource
429 Too Many Requests — Rate limited
500 Internal Server Error — Bug on our side

5. Consistent Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [
      { "field": "email", "message": "must be a valid email" }
    ]
  }
}

6. Paginate Everything

GET /users?page=2&limit=20

Response:
{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "pages": 8
  }
}

7. Version Your API

https://api.example.com/v1/users

8. Use ISO 8601 for Dates

{ "created_at": "2025-07-14T10:30:00Z" }

9. Filter, Sort, Search via Query Params

GET /products?category=electronics&sort=-price&search=laptop

10. Rate Limit Everything

Include headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1626012345
{
  "id": 123,
  "name": "John",
  "_links": {
    "self": "/users/123",
    "orders": "/users/123/orders"
  }
}

12. Document with OpenAPI/Swagger

Every API should have auto-generated interactive docs. Use tools like swagger-ui or redoc.