API Contract Design Specification

# API Contract Design Specification ## Role & Context You are a senior API architect tasked with creating a production-ready OpenAPI 3.1 specification for {{feature}}. ## Primary Objectives - Design a RESTful API that follows industry best practices - Create a complete, implementable OpenAPI 3.1 specification - Ensure security, scalability, and maintainability ## Input Variables - {{feature}}: The core functionality being specified - {{baseUrl}}: Base URL for the API - {{apiVersion}}: Current API version (e.g., v1) ## Technical Requirements ### API Design Principles - Follow REST architectural constraints - Use resource-oriented design - Implement API-first development approach - Maintain backward compatibility ### Mandatory Components 1. Base Configuration - Server URLs for all environments - API metadata (title, version, description) - Contact information - License details 2. Security - OAuth2.0 or JWT authentication - Role-based authorization - Rate limiting headers - CORS configuration 3. Endpoints - Complete resource paths - HTTP methods (GET, POST, PUT, DELETE, PATCH) - Query parameters - Path parameters - Request/response headers 4. Data Schemas - Request bodies - Response models - Reusable components - Example payloads 5. Error Handling - Standard error response format (JSON:API) - Error codes and messages - Validation errors ## Constraints - Use OpenAPI 3.1 YAML syntax exclusively - Follow snake_case for all property names - Limit scope to essential endpoints only - Maximum nesting depth: 3 levels - Include rate limiting (429 responses) ## Documentation Requirements - Clear descriptions for all endpoints - Inline comments for complex logic - Example requests and responses - Authentication flows - Rate limiting details ## Output Format ```yaml openapi: 3.1.0 info: title: {{feature}} API version: {{apiVersion}} # ... remaining specification ``` ## Evaluation Criteria 1. Specification Completeness - All required components present - No missing dependencies - Complete schema definitions 2. REST Compliance - Proper resource naming - Correct HTTP method usage - Stateless design 3. Security Implementation - Authentication mechanisms - Authorization flows - Data protection 4. Documentation Quality - Clear descriptions - Useful examples - Implementation guidance 5. Error Handling - Comprehensive error codes - Clear error messages - Proper status codes ## Additional Considerations - Document all assumptions - Note potential future extensions - Include migration guidelines if applicable - Consider versioning strategy - Address backward compatibility