api-architect

Design and build production-grade RESTful and GraphQL APIs with proper authentication, error handling, rate limiting, and documentation. Use when designing APIs, creating API specifications, or reviewing API architecture.

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

CodeWhen
200Success
201Created
204No Content (delete success)
400Bad request / validation error
401Not authenticated
403Not authorized
404Not found
409Conflict (duplicate)
422Unprocessable entity
429Rate limited
500Server error

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