@mytechtoday/augment-extensions 0.1.0 → 0.1.1

package/augment-extensions/domain-rules/api-design/rules/documentation.md

@@ -0,0 +1,395 @@
+# API Documentation
+
+Best practices for documenting APIs effectively.
+
+## OpenAPI/Swagger (Recommended)
+
+Use OpenAPI specification for REST APIs.
+
+```yaml
+# openapi.yaml
+openapi: 3.0.0
+info:
+  title: User API
+  version: 1.0.0
+  description: API for managing users
+  contact:
+    email: api@example.com
+  license:
+    name: MIT
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+  - url: https://staging-api.example.com/v1
+    description: Staging
+
+paths:
+  /users:
+    get:
+      summary: List users
+      description: Retrieve a paginated list of users
+      tags:
+        - Users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 20
+            maximum: 100
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserList'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    
+    post:
+      summary: Create user
+      description: Create a new user
+      tags:
+        - Users
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+      responses:
+        '201':
+          description: User created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '422':
+          $ref: '#/components/responses/ValidationError'
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+          example: "123"
+        name:
+          type: string
+          example: "John Doe"
+        email:
+          type: string
+          format: email
+          example: "john@example.com"
+        createdAt:
+          type: string
+          format: date-time
+    
+    CreateUserRequest:
+      type: object
+      required:
+        - name
+        - email
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+        email:
+          type: string
+          format: email
+    
+    UserList:
+      type: object
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/User'
+        meta:
+          $ref: '#/components/schemas/PaginationMeta'
+  
+  responses:
+    Unauthorized:
+      description: Authentication required
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    
+    ValidationError:
+      description: Validation failed
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ValidationError'
+  
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - bearerAuth: []
+```
+
+## GraphQL Documentation
+
+Use schema descriptions and tools like GraphQL Playground.
+
+```graphql
+"""
+Represents a user in the system
+"""
+type User {
+  """
+  Unique identifier for the user
+  """
+  id: ID!
+  
+  """
+  User's full name
+  """
+  name: String!
+  
+  """
+  User's email address (must be unique)
+  """
+  email: String!
+  
+  """
+  User's role in the system
+  """
+  role: UserRole!
+  
+  """
+  Timestamp when the user was created
+  """
+  createdAt: DateTime!
+}
+
+"""
+Available user roles
+"""
+enum UserRole {
+  """
+  Administrator with full access
+  """
+  ADMIN
+  
+  """
+  Regular user with limited access
+  """
+  USER
+}
+
+type Query {
+  """
+  Retrieve a single user by ID
+  
+  Returns null if user not found
+  """
+  user(
+    """
+    The unique identifier of the user
+    """
+    id: ID!
+  ): User
+  
+  """
+  List all users with optional filtering
+  
+  Supports pagination using cursor-based approach
+  """
+  users(
+    """
+    Filter by user role
+    """
+    role: UserRole
+    
+    """
+    Number of users to return (max 100)
+    """
+    first: Int = 20
+    
+    """
+    Cursor for pagination
+    """
+    after: String
+  ): UserConnection!
+}
+```
+
+## README Documentation
+
+Provide comprehensive README for API.
+
+```markdown
+# User API
+
+REST API for managing users.
+
+## Base URL
+
+```
+Production: https://api.example.com/v1
+Staging: https://staging-api.example.com/v1
+```
+
+## Authentication
+
+All endpoints require authentication using JWT tokens.
+
+```bash
+# Login to get token
+curl -X POST https://api.example.com/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com", "password": "secret"}'
+
+# Use token in requests
+curl https://api.example.com/v1/users \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+## Endpoints
+
+### List Users
+
+```
+GET /users
+```
+
+Query Parameters:
+- `page` (integer, default: 1) - Page number
+- `limit` (integer, default: 20, max: 100) - Items per page
+- `role` (string) - Filter by role (admin, user)
+
+Response:
+```json
+{
+  "data": [
+    {
+      "id": "123",
+      "name": "John Doe",
+      "email": "john@example.com"
+    }
+  ],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "limit": 20
+  }
+}
+```
+
+## Error Handling
+
+All errors follow this format:
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable message"
+  }
+}
+```
+
+Common error codes:
+- `VALIDATION_ERROR` (422) - Invalid input
+- `UNAUTHORIZED` (401) - Authentication required
+- `FORBIDDEN` (403) - Insufficient permissions
+- `NOT_FOUND` (404) - Resource not found
+
+## Rate Limiting
+
+- 1000 requests per hour per API key
+- Rate limit info in response headers:
+  - `X-RateLimit-Limit`
+  - `X-RateLimit-Remaining`
+  - `X-RateLimit-Reset`
+
+## Versioning
+
+API is versioned in the URL: `/v1/`, `/v2/`, etc.
+
+Current version: v1
+
+## SDKs
+
+- JavaScript: `npm install @example/api-client`
+- Python: `pip install example-api-client`
+
+## Support
+
+- Documentation: https://docs.example.com
+- Email: api@example.com
+- GitHub: https://github.com/example/api
+```
+
+## Code Examples
+
+Provide examples in multiple languages.
+
+```markdown
+## Examples
+
+### JavaScript
+
+```javascript
+const response = await fetch('https://api.example.com/v1/users', {
+  headers: {
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json'
+  }
+});
+const users = await response.json();
+```
+
+### Python
+
+```python
+import requests
+
+response = requests.get(
+    'https://api.example.com/v1/users',
+    headers={'Authorization': f'Bearer {token}'}
+)
+users = response.json()
+```
+
+### cURL
+
+```bash
+curl https://api.example.com/v1/users \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+```
+
+## Best Practices
+
+1. **Use OpenAPI** - For REST APIs
+2. **Use schema descriptions** - For GraphQL
+3. **Provide examples** - In multiple languages
+4. **Document errors** - List all error codes
+5. **Include authentication** - How to authenticate
+6. **Show rate limits** - Document limits
+7. **Version documentation** - Docs for each version
+8. **Interactive docs** - Swagger UI, GraphQL Playground
+9. **Keep updated** - Sync with code
+10. **Provide SDKs** - Client libraries
+11. **Include changelog** - Document changes
+12. **Add tutorials** - Getting started guides
+13. **Show use cases** - Common scenarios
+14. **Document webhooks** - If applicable
+15. **Provide support** - Contact information
+

package/augment-extensions/domain-rules/api-design/rules/error-handling.md

@@ -0,0 +1,290 @@
+# API Error Handling
+
+Best practices for handling and communicating errors in APIs.
+
+## Error Response Structure
+
+Use consistent error response format.
+
+```json
+// Good - Comprehensive error response
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed for one or more fields",
+    "details": [
+      {
+        "field": "email",
+        "message": "Email is required",
+        "code": "REQUIRED_FIELD"
+      },
+      {
+        "field": "age",
+        "message": "Age must be at least 18",
+        "code": "MIN_VALUE",
+        "value": 15,
+        "constraint": 18
+      }
+    ],
+    "timestamp": "2024-01-21T10:00:00Z",
+    "path": "/api/v1/users",
+    "requestId": "req_abc123"
+  }
+}
+
+// Good - Simple error
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "User not found",
+    "timestamp": "2024-01-21T10:00:00Z",
+    "requestId": "req_abc123"
+  }
+}
+```
+
+## HTTP Status Codes
+
+Use appropriate status codes for different error types.
+
+```
+# Client Errors (4xx)
+400 Bad Request          - Malformed request syntax
+401 Unauthorized         - Authentication required or failed
+403 Forbidden            - Authenticated but not authorized
+404 Not Found            - Resource doesn't exist
+405 Method Not Allowed   - HTTP method not supported
+409 Conflict             - Resource conflict (e.g., duplicate)
+410 Gone                 - Resource permanently deleted
+422 Unprocessable Entity - Validation errors
+429 Too Many Requests    - Rate limit exceeded
+
+# Server Errors (5xx)
+500 Internal Server Error - Unexpected server error
+502 Bad Gateway          - Invalid response from upstream
+503 Service Unavailable  - Server temporarily unavailable
+504 Gateway Timeout      - Upstream server timeout
+```
+
+## Error Codes
+
+Define machine-readable error codes.
+
+```typescript
+// Good - Enum of error codes
+enum ErrorCode {
+  // Validation errors (4xx)
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  REQUIRED_FIELD = 'REQUIRED_FIELD',
+  INVALID_FORMAT = 'INVALID_FORMAT',
+  MIN_LENGTH = 'MIN_LENGTH',
+  MAX_LENGTH = 'MAX_LENGTH',
+  
+  // Authentication errors (401)
+  INVALID_CREDENTIALS = 'INVALID_CREDENTIALS',
+  TOKEN_EXPIRED = 'TOKEN_EXPIRED',
+  TOKEN_INVALID = 'TOKEN_INVALID',
+  
+  // Authorization errors (403)
+  INSUFFICIENT_PERMISSIONS = 'INSUFFICIENT_PERMISSIONS',
+  RESOURCE_FORBIDDEN = 'RESOURCE_FORBIDDEN',
+  
+  // Not found errors (404)
+  RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
+  ENDPOINT_NOT_FOUND = 'ENDPOINT_NOT_FOUND',
+  
+  // Conflict errors (409)
+  DUPLICATE_RESOURCE = 'DUPLICATE_RESOURCE',
+  RESOURCE_CONFLICT = 'RESOURCE_CONFLICT',
+  
+  // Rate limiting (429)
+  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
+  
+  // Server errors (5xx)
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  DATABASE_ERROR = 'DATABASE_ERROR',
+  EXTERNAL_SERVICE_ERROR = 'EXTERNAL_SERVICE_ERROR'
+}
+```
+
+## Validation Errors
+
+Provide detailed validation error information.
+
+```json
+// Good - Field-level validation errors
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Email must be a valid email address",
+        "code": "INVALID_FORMAT",
+        "value": "not-an-email"
+      },
+      {
+        "field": "password",
+        "message": "Password must be at least 8 characters",
+        "code": "MIN_LENGTH",
+        "value": "***",
+        "constraint": 8
+      },
+      {
+        "field": "age",
+        "message": "Age must be between 18 and 120",
+        "code": "OUT_OF_RANGE",
+        "value": 150,
+        "min": 18,
+        "max": 120
+      }
+    ]
+  }
+}
+```
+
+## Authentication Errors
+
+Handle authentication failures clearly.
+
+```json
+// 401 Unauthorized - Invalid credentials
+{
+  "error": {
+    "code": "INVALID_CREDENTIALS",
+    "message": "Invalid email or password",
+    "timestamp": "2024-01-21T10:00:00Z"
+  }
+}
+
+// 401 Unauthorized - Token expired
+{
+  "error": {
+    "code": "TOKEN_EXPIRED",
+    "message": "Access token has expired",
+    "expiredAt": "2024-01-21T09:00:00Z",
+    "hint": "Use refresh token to obtain a new access token"
+  }
+}
+
+// 401 Unauthorized - Invalid token
+{
+  "error": {
+    "code": "TOKEN_INVALID",
+    "message": "Invalid or malformed access token"
+  }
+}
+```
+
+## Authorization Errors
+
+Communicate permission issues.
+
+```json
+// 403 Forbidden - Insufficient permissions
+{
+  "error": {
+    "code": "INSUFFICIENT_PERMISSIONS",
+    "message": "You don't have permission to perform this action",
+    "requiredPermission": "write:users",
+    "userPermissions": ["read:users"]
+  }
+}
+
+// 403 Forbidden - Resource forbidden
+{
+  "error": {
+    "code": "RESOURCE_FORBIDDEN",
+    "message": "You don't have access to this resource"
+  }
+}
+```
+
+## Not Found Errors
+
+Distinguish between different types of "not found".
+
+```json
+// 404 Not Found - Resource
+{
+  "error": {
+    "code": "RESOURCE_NOT_FOUND",
+    "message": "User not found",
+    "resourceType": "User",
+    "resourceId": "123"
+  }
+}
+
+// 404 Not Found - Endpoint
+{
+  "error": {
+    "code": "ENDPOINT_NOT_FOUND",
+    "message": "The requested endpoint does not exist",
+    "path": "/api/v1/invalid-endpoint"
+  }
+}
+```
+
+## Rate Limiting Errors
+
+Provide retry information.
+
+```json
+// 429 Too Many Requests
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "Too many requests. Please try again later.",
+    "limit": 1000,
+    "remaining": 0,
+    "resetAt": "2024-01-21T11:00:00Z",
+    "retryAfter": 3600
+  }
+}
+```
+
+## Server Errors
+
+Handle internal errors gracefully.
+
+```json
+// 500 Internal Server Error
+{
+  "error": {
+    "code": "INTERNAL_ERROR",
+    "message": "An unexpected error occurred. Please try again later.",
+    "requestId": "req_abc123",
+    "timestamp": "2024-01-21T10:00:00Z"
+  }
+}
+
+// Don't expose internal details in production
+// Bad - Exposing stack trace
+{
+  "error": {
+    "message": "Database connection failed",
+    "stack": "Error: connect ECONNREFUSED...",  // ❌ Don't expose
+    "query": "SELECT * FROM users WHERE..."     // ❌ Don't expose
+  }
+}
+```
+
+## Best Practices
+
+1. **Use consistent format** - Same structure for all errors
+2. **Use proper status codes** - Match HTTP semantics
+3. **Provide error codes** - Machine-readable codes
+4. **Include helpful messages** - Human-readable descriptions
+5. **Field-level errors** - For validation failures
+6. **Include request ID** - For debugging and support
+7. **Include timestamp** - When error occurred
+8. **Don't expose internals** - Hide stack traces in production
+9. **Log errors** - Server-side logging for debugging
+10. **Document errors** - List possible error codes
+11. **Localize messages** - Support multiple languages
+12. **Provide hints** - Suggest how to fix the error
+13. **Rate limit info** - Include retry information
+14. **Validate early** - Fail fast on invalid input
+15. **Monitor errors** - Track error rates and types
+