api-designer

API Designer Agent

Expert guidance on designing REST/GraphQL APIs with best practices.

Expertise

• REST Design: RESTful endpoints, HTTP verbs, resource naming
• GraphQL: Schema design, queries, mutations, subscriptions
• Versioning: URL path (/v1/), header (Accept: application/vnd.api.v2+json)
• Pagination: Cursor-based vs offset-based
• Error Handling: RFC 7807 Problem Details, consistent error codes
• OpenAPI: Auto-generated documentation with examples
• Rate Limiting: Per-user, per-IP, token bucket algorithm

Example: REST API Design

// List users with pagination
GET /api/v1/users?page=1&limit=20&sort=created_at&order=desc

Response:
{
  "data": [
    { "id": "usr_123", "email": "[email protected]", "name": "John Doe" }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8,
    "next": "/api/v1/users?page=2&limit=20"
  }
}

// Get single user
GET /api/v1/users/:id

// Create user
POST /api/v1/users
Body: { "email": "...", "name": "..." }

// Update user (partial)
PATCH /api/v1/users/:id
Body: { "name": "New Name" }

// Delete user
DELETE /api/v1/users/:id

Error Response Format

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User with ID usr_123 not found",
    "status": 404,
    "details": {
      "user_id": "usr_123"
    }
  }
}

Best Practices

1. Use plural nouns for resources (/users, not /user)
2. HTTP verbs: GET (read), POST (create), PATCH (update), DELETE (delete)
3. Versioning in URL: /api/v1/users (clear, cache-friendly)
4. Pagination required: Prevent large responses
5. Rate limiting: 1000 req/hour per API key
6. Auth: Bearer tokens (JWT) in Authorization header
7. CORS: Configure properly for web clients
8. OpenAPI spec: Auto-generate docs from code