Cursor rule

1---
2description: RESTful API design and documentation standards
3globs: *.php, *.js, *.ts
4---
5# Enhanced API Standards
6 
7Ensures consistent API design, documentation, and implementation best practices across PHP, JavaScript, and TypeScript files.
8 
9## Rule Details
10 
11- **Name:** enhanced_api_standards
12 
13- **Description:** Enforce enhanced API design, implementation, and documentation standards
14 
15## Filters
16- file extension pattern: `\\.(php|js|ts)$`
17 
18## Enforcement Checks
19- Conditions:
20  - pattern `@api\\s+(?!GET|POST|PUT|DELETE|PATCH|OPTIONS|HEAD)` – Use standard HTTP methods (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD) for API endpoints.
21  - pattern `function\\s+[a-zA-Z]+Api\\s*\\([^)]*\\)\\s*\\{[^}]*\\}` – negated `(?s)(throw new \\w+Exception|return\\s+(?:\\d{3}|4\\d\\d|5\\d\\d))` – Ensure API functions handle or return errors appropriately using exceptions or HTTP status codes.
22  - pattern `(?<!@api\\s+)(?<!\\s+returns\\s+)(?<!\\s+throws\\s+)[A-Z]{3,}(?!\\s+)` – HTTP methods should be prefixed with '@api' for documentation purposes.
23  - pattern `\\bresponse\\b(?![^;]*\\.json\\()` – Ensure all API responses are properly formatted, preferably as JSON.
24 
25## Suggestions
26- Guidance:
27**API Best Practices:**
28- **HTTP Methods:** Use proper HTTP methods for operations (GET for retrieval, POST for creation, etc.).
29- **Status Codes:** Use appropriate HTTP status codes to communicate the result of the request.
30- **Versioning:** Implement API versioning to manage changes without breaking existing integrations.
31- **Documentation:** 
32  - **Swagger/OpenAPI:** Use tools like Swagger for comprehensive API documentation.
33  - **Endpoint Descriptions:** Clearly document all endpoints including path, methods, parameters, and possible responses.
34- **Authentication & Security:**
35  - Implement OAuth, JWT, or similar secure authentication methods.
36  - Use HTTPS for all API communications.
37- **Rate Limiting:** Implement rate limiting to prevent abuse and ensure fair usage.
38- **Error Handling:** 
39  - Provide clear, human-readable error messages with corresponding status codes.
40  - Implement error logging for debugging purposes.
41- **Pagination:** For list endpoints, implement pagination to manage large datasets.
42- **Validation:** Validate input data at the API level to ensure data integrity.
43- **CORS:** Configure CORS headers if your API is meant to be consumed by web applications from different domains.
44- **Monitoring:** Set up monitoring for API performance and usage statistics.
45 
46## Metadata
47- Priority: high
48- Version: 1.2
49