Prompt

You are an API architect tasked with designing a comprehensive RESTful API for [APPLICATION/SERVICE_NAME]. Your goal is to create a detailed API design specification and documentation that meets the following criteria:

## API Strategy & Design Principles

**API Strategy:**
- **Purpose:** Clearly define the business objectives, target consumers, and value proposition of the API.
- **Type:** Specify whether the API is public, partner, internal, or hybrid.
- **Integration Patterns:** Identify the integration patterns such as RESTful, GraphQL, event-driven, or microservices.
- **Technology Stack:** Outline the framework, database, authentication methods, and hosting platform to be used.
- **Versioning Strategy:** Describe the versioning approach, including semantic versioning, deprecation policy, and migration support.

**Design Principles:**
- **RESTful Design:** Ensure resource-oriented architecture, proper HTTP method semantics, and statelessness.
- **Consistency:** Maintain uniform naming conventions, response formats, and error handling.
- **Simplicity:** Design an intuitive interface with minimal cognitive load and provide clear documentation.
- **Security-First:** Implement robust authentication, authorization, data protection, and input validation measures.
- **Performance:** Focus on efficient data transfer, caching, pagination, and compression techniques.
- **Extensibility:** Ensure forward compatibility, effective versioning, and the use of feature flags.

## Resource Design & URL Structure

**Resource Identification:**
- Identify core entities and their relationships, including parent-child relationships and nested resources.
- Define collection resources with capabilities for filtering, sorting, and pagination.
- Specify singleton resources such as unique resources or configuration objects.

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

- **Collections:**
  - GET /users - Retrieve all users.
  - POST /users - Create a new user.
  - GET /users/{id} - Retrieve a 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 - Retrieve user's orders.
  - POST /users/{id}/orders - Create an order for a 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

## Request/Response Design

**Request Structure:**
- **Headers:** Include Content-Type, Authorization, Accept, X-API-Version, and X-Request-ID.
- **Body Example:** Provide a JSON example for user creation, ensuring to include required fields.

**Response Structure:**
- Define a standard JSON response format, including status, data, and meta information.

**HTTP Status Codes:**
- Clearly outline the expected HTTP status codes for success, redirection, client errors, and server errors.

## Authentication & Authorization

**Authentication Methods:**
- Describe methods such as API Keys, OAuth 2.0, JWT Tokens, and Basic Authentication.

**OAuth 2.0 Implementation Steps:**
1. Client Registration
2. Authorization Request
3. Token Exchange
4. API Access

**Authorization Model:**
- Define role-based and attribute-based access control mechanisms.

## Performance & Scalability

**Pagination Design:**
- Provide a JSON structure for pagination, including links for navigation.

**Caching Strategy:**
- Outline strategies for HTTP caching, application caching, CDN caching, and database caching.

**Rate Limiting:**
- Specify rate limit headers and response formats for exceeding limits.

## Error Handling & Monitoring

**Error Classification:**
- Classify errors into client errors, server errors, business logic errors, and integration errors.

**Error Response Format:**
- Provide a standard JSON error response format.

**Monitoring & Metrics:**
- Define metrics for API performance, business usage, and infrastructure health.

## Documentation & Testing

**API Documentation Structure:**
- Outline the necessary sections for API documentation, including getting started guides, API references, SDKs, and testing strategies.

**Testing Strategy:**
- Describe unit, integration, contract, performance, and security testing approaches.

**API Versioning & Deployment:**
- Specify versioning strategies and deployment methods.

Include specific code examples, configuration details, and implementation guidelines throughout the API design. Ensure to handle edge cases, such as invalid inputs or unauthorized access, and provide clear error messages for each scenario.