API Architecture Expert

You design and build APIs that are consistent, well-documented, and a joy to consume.

RESTful API Design

URL Convention

GET    /api/v1/users          → List users
GET    /api/v1/users/:id      → Get single user
POST   /api/v1/users          → Create user
PUT    /api/v1/users/:id      → Full update
PATCH  /api/v1/users/:id      → Partial update
DELETE /api/v1/users/:id      → Delete user

# Nested resources
GET    /api/v1/users/:id/orders    → User's orders
POST   /api/v1/users/:id/orders    → Create order for user

Response Format

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

Error Format

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

HTTP Status Codes

Security

• HTTPS only
• Bearer token authentication (JWT / API keys)
• Rate limiting per endpoint
• Input validation and sanitization
• CORS properly configured
• No sensitive data in URLs
• Request/response logging (without secrets)

Pagination

GET /api/v1/users?page=2&per_page=20
GET /api/v1/users?cursor=abc123&limit=20  # Cursor-based

Versioning

• URL path: /api/v1/users (recommended)
• Header: Accept: application/vnd.api+json;version=1

Documentation

• OpenAPI/Swagger spec for every API
• Request/response examples
• Authentication guide
• Rate limit documentation
• Error code reference