Prompt

You are an API architect designing a comprehensive RESTful API for [APPLICATION/SERVICE_NAME].

Create a detailed API design specification and documentation:

## API Strategy & Design Principles

**API Strategy:**
- API purpose: [Business objectives, target consumers, value proposition]
- API type: [Public, partner, internal, hybrid API strategy]
- Integration patterns: [RESTful, GraphQL, event-driven, microservices]
- Technology stack: [Framework, database, authentication, hosting platform]
- Versioning strategy: [Semantic versioning, deprecation policy, migration support]

**Design Principles:**
- RESTful design: [Resource-oriented, HTTP method semantics, stateless]
- Consistency: [Naming conventions, response formats, error handling]
- Simplicity: [Intuitive interface, minimal cognitive load, clear documentation]
- Security-first: [Authentication, authorization, data protection, input validation]
- Performance: [Efficient data transfer, caching, pagination, compression]
- Extensibility: [Forward compatibility, versioning, feature flags]

## Resource Design & URL Structure

**Resource Identification:**
- Core entities: [Primary business objects and their relationships]
- Resource hierarchy: [Parent-child relationships, nested resources]
- Collection resources: [Lists, filtering, sorting, pagination]
- Singleton resources: [Unique resources, configuration objects]

**URL Design Patterns:**
Base URL: https://api.example.com/v1

Collections:
GET    /users                    # Get all users
POST   /users                    # Create new user
GET    /users/{id}              # Get specific user
PUT    /users/{id}              # Update user (full)
PATCH  /users/{id}              # Update user (partial)
DELETE /users/{id}              # Delete user

Nested Resources:
GET    /users/{id}/orders       # Get user's orders
POST   /users/{id}/orders       # Create order for user

Filtering and Querying:
GET    /users?status=active&sort=name&limit=50&offset=0
GET    /orders?date_from=2023-01-01&date_to=2023-12-31

**HTTP Method Usage:**
- GET: [Safe, idempotent, retrieval operations, no side effects]
- POST: [Resource creation, non-idempotent operations, actions]
- PUT: [Full resource replacement, idempotent updates]
- PATCH: [Partial resource updates, field-specific modifications]
- DELETE: [Resource removal, idempotent deletion]

## Request/Response Design

**Request Structure:**
Headers:
- Content-Type: application/json
- Authorization: Bearer {access_token}
- Accept: application/json
- X-API-Version: 1.0
- X-Request-ID: uuid-string

Body example:
{
  "user": {
    "name": "John Doe",
    "email": "john@example.com",
    "preferences": {
      "notifications": true,
      "language": "en"
    }
  }
}

**Response Structure:**
{
  "status": {
    "code": 200,
    "message": "Success"
  },
  "data": {
    "user": {
      "id": "12345",
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  },
  "meta": {
    "request_id": "uuid-string",
    "timestamp": "2023-01-01T00:00:00Z",
    "version": "1.0"
  }
}

**HTTP Status Codes:**
- 2xx Success: 200 OK, 201 Created, 202 Accepted, 204 No Content
- 3xx Redirection: 301 Moved Permanently, 302 Found, 304 Not Modified
- 4xx Client Error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
- 5xx Server Error: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable

## Authentication & Authorization

**Authentication Methods:**
- API Keys: [Simple authentication, service-to-service communication]
- OAuth 2.0: [Delegated authorization, third-party integrations]
- JWT Tokens: [Stateless authentication, microservices architecture]
- Basic Authentication: [Simple username/password, HTTPS required]

**OAuth 2.0 Implementation:**
1. Client Registration - Register application with OAuth provider
2. Authorization Request - User grants permission to application
3. Token Exchange - Exchange authorization code for access token
4. API Access - Use access token to authenticate API requests

**Authorization Model:**
- Role-based access control (RBAC): [User roles, permission assignment]
- Attribute-based access control (ABAC): [Dynamic permissions, context-aware]
- Resource-level permissions: [Object-specific access control]
- Scope-based permissions: [OAuth scopes, limited access grants]

## Performance & Scalability

**Pagination Design:**
{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1250,
    "total_pages": 25,
    "has_next": true,
    "has_previous": false
  },
  "links": {
    "first": "/users?page=1&per_page=50",
    "last": "/users?page=25&per_page=50",
    "next": "/users?page=2&per_page=50",
    "self": "/users?page=1&per_page=50"
  }
}

**Caching Strategy:**
- HTTP Caching: [Cache-Control, ETag, Last-Modified headers]
- Application caching: [Redis, Memcached, in-memory caching]
- CDN caching: [Geographic distribution, static content caching]
- Database caching: [Query result caching, connection pooling]

**Rate Limiting:**
Rate Limit Headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Rate Limiting Response (429):
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "reset_time": "2023-01-01T00:00:00Z"
    }
  }
}

## Error Handling & Monitoring

**Error Classification:**
- Client errors (4xx): [Invalid input, authentication, authorization]
- Server errors (5xx): [Application bugs, infrastructure issues, dependencies]
- Business logic errors: [Domain-specific validation, workflow violations]
- Integration errors: [External service failures, network issues]

**Error Response Format:**
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email format is invalid",
        "value": "invalid-email"
      }
    ],
    "timestamp": "2023-01-01T00:00:00Z",
    "request_id": "uuid-string"
  }
}

**Monitoring & Metrics:**
- API metrics: [Request count, response time, error rate, throughput]
- Business metrics: [User activity, feature usage, conversion rates]
- Infrastructure metrics: [CPU, memory, disk, network utilization]
- Custom metrics: [Domain-specific KPIs, business intelligence]

## Documentation & Testing

**API Documentation Structure:**
- Getting started guide: [Authentication, basic usage, quick start]
- API reference: [Endpoints, parameters, responses, examples]
- SDKs and libraries: [Language-specific clients, code examples]
- Tutorials and guides: [Common use cases, best practices, troubleshooting]
- Changelog: [Version history, breaking changes, migration guides]

**Testing Strategy:**
- Unit testing: [Individual endpoint testing, business logic validation]
- Integration testing: [End-to-end workflows, database interactions]
- Contract testing: [API specification compliance, consumer-driven contracts]
- Performance testing: [Load testing, stress testing, benchmark testing]
- Security testing: [Vulnerability scanning, penetration testing]

**API Versioning & Deployment:**
- URL versioning: [/v1/users, /v2/users path-based versioning]
- Header versioning: [Accept: application/vnd.api+json;version=1]
- Parameter versioning: [?version=1.0 query parameter]
- Deployment strategy: [Blue-green, canary, rolling deployment]

Include specific code examples, configuration details, and implementation guidelines throughout the API design.