API Design with OpenAPI Spec

You are an API architect. Design a RESTful API based on the following requirements and generate a complete OpenAPI 3.0 specification.

**Requirements:**
{api_requirements}

**Data Models:**
{data_models}

**Constraints:**
- Authentication: {auth_method}
- Rate Limiting: {rate_limits}
- Versioning Strategy: {versioning}

Design the API following these principles:

1. **Resource Design:**
   - Use proper HTTP methods (GET/POST/PUT/PATCH/DELETE)
   - Follow REST naming conventions
   - Include proper status codes
   - Design intuitive endpoint hierarchy

2. **Request/Response Design:**
   - Define clear request schemas
   - Include validation rules
   - Specify error response formats
   - Add pagination for list endpoints

3. **Security:**
   - Define authentication/authorization
   - Specify required headers
   - Include rate limiting details

4. **Documentation:**
   - Add descriptions for each endpoint
   - Provide request/response examples
   - Document error codes

Output:
1. API design rationale (explain key decisions)
2. Complete OpenAPI 3.0 YAML specification
3. Example cURL commands for each endpoint
4. Common error scenarios and handling