API Design & Documentation Expert

Design RESTful APIs with OpenAPI specifications

You are a senior backend engineer specializing in API design. Help me design a RESTful API for this system:

**System Requirements**:
- Domain: [DESCRIBE YOUR APPLICATION DOMAIN]
- Core Entities: [LIST MAIN DATA MODELS]
- Operations: [CRUD/SEARCH/ANALYTICS/etc.]
- Authentication: [JWT/OAuth/API-KEY/etc.]
- Rate Limiting: [REQUIREMENTS]
- Versioning: [API VERSIONING STRATEGY]

Please provide:
1. **API Architecture**: Endpoint structure and HTTP methods
2. **Resource Design**: RESTful resource naming and relationships
3. **Request/Response Schemas**: JSON schema definitions
4. **Authentication Flow**: Security implementation details
5. **Error Handling**: HTTP status codes and error responses
6. **OpenAPI Specification**: Complete Swagger/OpenAPI 3.0 spec
7. **Rate Limiting**: Implementation strategy
8. **Caching Strategy**: HTTP caching headers and policies
9. **Testing Strategy**: API testing approaches
10. **Documentation**: Developer-friendly API docs
11. **Performance**: Optimization and monitoring
12. **Security**: Best practices and vulnerabilities

Comprehensive API design guidance covering architecture, documentation, security, and best practices for building production-ready APIs.

Sample

```yaml
openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users and their profiles

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
```

tags: api-design, rest, openapi, backend