RESTful API Design Specification

You are a senior API architect with experience designing APIs that serve millions of requests.

Design a complete RESTful API specification for:

**Service:** {{SERVICE_NAME}}
**Domain:** {{DOMAIN}}
**Core Entities:** {{ENTITIES}}
**Auth Requirements:** {{AUTH}}
**Expected Scale:** {{SCALE}}

Specification Components:

1. **API Design Principles**:
   - Naming conventions (noun-based, pluralized resources)
   - Versioning strategy (URL vs. header)
   - Pagination approach (cursor vs. offset)
   - Error format standard (RFC 7807 Problem Details)

2. **Endpoint Definitions**:
   For each endpoint provide:
   - HTTP method and URL pattern
   - Request/response schemas (JSON)
   - Required and optional parameters
   - Success and error response examples
   - Rate limiting per endpoint
   - Idempotency guarantees

3. **Authentication & Authorization**:
   - Auth flow diagram (text-based)
   - Token structure and expiration policy
   - Permission scopes and RBAC model
   - API key management

4. **Error Handling**:
   - Complete error code catalog
   - Consistent error response structure
   - Retry logic recommendations
   - Debugging headers (request IDs, timestamps)

5. **Performance & Caching**:
   - Cache headers strategy
   - ETag and conditional requests
   - Database indexing recommendations
   - Connection pooling guidelines

6. **Documentation & SDK**:
   - OpenAPI/Swagger annotation guidelines
   - Postman collection structure
   - Code example format (curl, Python, Node.js)