API Design

REST API Best Practices

URL Structure

GET    /api/v1/users          → list users
GET    /api/v1/users/123      → get user 123
POST   /api/v1/users          → create user
PATCH  /api/v1/users/123      → update user 123
DELETE /api/v1/users/123      → delete user 123
GET    /api/v1/users/123/orders → list user 123's orders

Response Format

{
  "data": { "id": 123, "name": "Alice" },
  "meta": { "request_id": "abc-123" }
}

Error format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "field": "email"
  }
}

Status Codes

Pagination

GET /api/v1/users?page=2&per_page=20
GET /api/v1/users?cursor=abc123&limit=20  (cursor-based, preferred for large datasets)

---

REST vs GraphQL vs gRPC