wicked-garden 12.27.0

package/skills/engineering/integration/refs/rest-api-responses-security.md

@@ -0,0 +1,302 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# REST API Design - Responses, Headers, Security, and Best Practices
+
+Response formats, status codes, headers, advanced patterns, security, and best practices.
+
+## Response Formats
+
+### Success Response Structure
+
+```json
+{
+  "data": {
+    "id": 123,
+    "type": "user",
+    "attributes": {
+      "name": "Alice",
+      "email": "alice@example.com"
+    },
+    "relationships": {
+      "organization": {
+        "data": { "type": "organization", "id": 456 }
+      }
+    }
+  },
+  "meta": {
+    "version": "1.0",
+    "timestamp": "2025-01-24T10:00:00Z"
+  }
+}
+```
+
+**Simpler Alternative**
+```json
+{
+  "id": 123,
+  "name": "Alice",
+  "email": "alice@example.com",
+  "organization_id": 456
+}
+```
+
+### Error Response Structure
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format",
+        "value": "not-an-email"
+      }
+    ],
+    "request_id": "req_abc123",
+    "timestamp": "2025-01-24T10:00:00Z"
+  }
+}
+```
+
+### Collection Response
+
+```json
+{
+  "data": [
+    { "id": 1, "name": "Alice" },
+    { "id": 2, "name": "Bob" }
+  ],
+  "pagination": {
+    "total": 150,
+    "page": 3,
+    "per_page": 20,
+    "total_pages": 8
+  },
+  "links": {
+    "self": "/users?page=3",
+    "first": "/users?page=1",
+    "prev": "/users?page=2",
+    "next": "/users?page=4",
+    "last": "/users?page=8"
+  }
+}
+```
+
+## Status Codes
+
+### 2xx Success
+
+| Code | Meaning | Use Case |
+|------|---------|----------|
+| 200 | OK | Successful GET, PUT, PATCH, DELETE with body |
+| 201 | Created | Successful POST creating resource |
+| 202 | Accepted | Async processing started |
+| 204 | No Content | Successful DELETE without body |
+
+### 3xx Redirection
+
+| Code | Meaning | Use Case |
+|------|---------|----------|
+| 301 | Moved Permanently | Resource URL changed |
+| 302 | Found | Temporary redirect |
+| 304 | Not Modified | Cached version still valid |
+
+### 4xx Client Errors
+
+| Code | Meaning | Use Case |
+|------|---------|----------|
+| 400 | Bad Request | Invalid syntax, validation failed |
+| 401 | Unauthorized | Missing or invalid authentication |
+| 403 | Forbidden | Authenticated but not authorized |
+| 404 | Not Found | Resource doesn't exist |
+| 405 | Method Not Allowed | GET on POST-only endpoint |
+| 409 | Conflict | Resource state conflict |
+| 422 | Unprocessable Entity | Semantic validation failed |
+| 429 | Too Many Requests | Rate limit exceeded |
+
+### 5xx Server Errors
+
+| Code | Meaning | Use Case |
+|------|---------|----------|
+| 500 | Internal Server Error | Unexpected error |
+| 502 | Bad Gateway | Invalid upstream response |
+| 503 | Service Unavailable | Temporary unavailable |
+| 504 | Gateway Timeout | Upstream timeout |
+
+## Headers
+
+### Request Headers
+
+```http
+# Authentication
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+
+# Content negotiation
+Accept: application/json
+Accept-Language: en-US,en;q=0.9
+Accept-Encoding: gzip, deflate
+
+# Conditional requests
+If-None-Match: "686897696a7c876b7e"
+If-Modified-Since: Wed, 21 Jan 2025 07:28:00 GMT
+
+# Idempotency
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+
+# API Version
+Accept: application/vnd.api+json; version=2
+```
+
+### Response Headers
+
+```http
+# Content type
+Content-Type: application/json; charset=utf-8
+
+# Caching
+Cache-Control: max-age=3600, must-revalidate
+ETag: "686897696a7c876b7e"
+Last-Modified: Wed, 21 Jan 2025 07:28:00 GMT
+
+# Rate limiting
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1611218400
+
+# CORS
+Access-Control-Allow-Origin: https://example.com
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE
+Access-Control-Allow-Headers: Authorization, Content-Type
+
+# Location of created resource
+Location: /users/123
+
+# Request tracking
+X-Request-ID: req_abc123
+```
+
+## Advanced Patterns
+
+### Bulk Operations
+
+```http
+# Batch create
+POST /users/batch
+[
+  { "name": "Alice", "email": "alice@example.com" },
+  { "name": "Bob", "email": "bob@example.com" }
+]
+
+Response: 201 Created
+{
+  "created": 2,
+  "results": [
+    { "id": 1, "name": "Alice", "status": "created" },
+    { "id": 2, "name": "Bob", "status": "created" }
+  ]
+}
+
+# Batch update
+PATCH /users/batch
+[
+  { "id": 1, "email": "newalice@example.com" },
+  { "id": 2, "email": "newbob@example.com" }
+]
+```
+
+### Async Operations
+
+```http
+# Start long-running job
+POST /reports/generate
+{ "type": "annual", "year": 2024 }
+
+Response: 202 Accepted
+Location: /jobs/abc-123
+{
+  "job_id": "abc-123",
+  "status": "processing",
+  "estimated_completion": "2025-01-24T10:05:00Z"
+}
+
+# Check status
+GET /jobs/abc-123
+
+Response: 200 OK
+{
+  "job_id": "abc-123",
+  "status": "completed",
+  "result": {
+    "download_url": "/reports/annual-2024.pdf"
+  }
+}
+```
+
+### Webhooks
+
+```http
+POST /webhooks
+{ "url": "https://example.com/webhook", "events": ["order.created"], "secret": "whsec_abc123" }
+
+Response: 201 Created
+{ "id": "wh_123", "url": "https://example.com/webhook", "events": ["order.created"], "created_at": "..." }
+```
+
+## Security
+
+### Authentication
+
+**Bearer Token**
+```http
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+**API Key**
+```http
+X-API-Key: pk_live_abc123def456
+```
+
+**Basic Auth** (HTTPS only): `Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=`
+
+### Rate Limiting
+
+```http
+Response Headers:
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1611218400
+Retry-After: 3600
+
+Response: 429 Too Many Requests
+{
+  "error": "Rate limit exceeded",
+  "retry_after": 3600
+}
+```
+
+### CORS
+
+```http
+# Preflight response
+Access-Control-Allow-Origin: https://example.com
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE
+Access-Control-Allow-Headers: Authorization, Content-Type
+Access-Control-Max-Age: 86400
+```
+
+## Best Practices
+
+1. **Use proper HTTP methods** — GET/POST/PUT/PATCH/DELETE; don't use POST for everything
+2. **Version your API** — URL (`/v1/users`), header, or content-type versioning
+3. **Handle errors gracefully** — appropriate status code, clear message, request ID, actionable guidance
+4. **Document everything** — OpenAPI/Swagger specification (see openapi-template.yaml)
+5. **Idempotency** — support `Idempotency-Key` header for POST/PATCH
+6. **Pagination** — always paginate collections; never return unbounded arrays
+7. **Use HTTPS** — TLS 1.2+ in all production environments
+8. **Validate early** — fail fast with clear field-level error messages
+9. **Consistency** — uniform naming (camelCase or snake_case), error format, ISO 8601 timestamps
+10. **Monitoring** — log every request: request ID, user ID, response time, status code

package/skills/engineering/integration/refs/versioning-breaking-changes.md

@@ -0,0 +1,237 @@
+---
+phase_relevance: ["design", "build"]
+archetype_relevance: ["*"]
+---
+# API Versioning Guide: Breaking Changes
+
+## Breaking Changes
+
+### User Endpoint
+
+**Changed**: User ID format
+- **V1**: Integer ID (`123`)
+- **V2**: String UUID (`550e8400-e29b-41d4-a716-446655440000`)
+
+**Migration**: Update client code to handle string IDs.
+
+### Order Endpoint
+
+**Removed**: `order_date` field
+**Replaced by**: `created_at` (ISO 8601 timestamp)
+
+**Migration**:
+```typescript
+// V1
+const date = response.order_date;
+
+// V2
+const date = new Date(response.created_at);
+```
+```
+
+### 3. Provide Migration Tools
+
+```typescript
+// Migration script
+async function migrateV1toV2() {
+  const v1Users = await fetchV1Users();
+
+  for (const user of v1Users) {
+    const v2User = {
+      id: generateUUID(user.id),  // Convert ID
+      name: user.name,
+      email: user.email || `user${user.id}@example.com`,  // Add required field
+      createdAt: user.created_date.toISOString()  // Convert format
+    };
+
+    await createV2User(v2User);
+  }
+}
+```
+
+### 4. Sunset Old Versions
+
+Set clear timelines:
+
+```typescript
+const VERSION_LIFECYCLE = {
+  'v1': {
+    released: '2023-01-01',
+    deprecated: '2024-01-01',
+    sunset: '2025-01-01'  // 2 years support
+  },
+  'v2': {
+    released: '2024-01-01',
+    deprecated: null,
+    sunset: null
+  }
+};
+```
+
+### 5. Monitor Version Usage
+
+```typescript
+app.use((req, res, next) => {
+  const version = req.apiVersion;
+
+  // Track version usage
+  metrics.increment('api.version.usage', {
+    version,
+    endpoint: req.path
+  });
+
+  next();
+});
+```
+
+### 6. Test Backward Compatibility
+
+```typescript
+describe('API Compatibility', () => {
+  it('V2 should accept V1 request format', async () => {
+    const v1Request = {
+      user_name: 'Alice',
+      user_email: 'alice@example.com'
+    };
+
+    const response = await request(app)
+      .post('/api/v2/users')
+      .send(v1Request);
+
+    expect(response.status).toBe(201);
+  });
+
+  it('V2 response should include V1 fields', async () => {
+    const response = await request(app)
+      .get('/api/v2/users/123')
+      .set('Accept-Version', '2');
+
+    // New V2 field
+    expect(response.body).toHaveProperty('email');
+
+    // Deprecated V1 field still present
+    expect(response.body).toHaveProperty('user_name');
+  });
+});
+```
+
+### 7. Version Discovery
+
+Provide version information endpoint:
+
+```typescript
+app.get('/api/versions', (req, res) => {
+  res.json({
+    versions: [
+      {
+        version: '1',
+        status: 'deprecated',
+        released: '2023-01-01',
+        deprecated: '2024-01-01',
+        sunset: '2025-01-01',
+        docs: 'https://docs.example.com/api/v1'
+      },
+      {
+        version: '2',
+        status: 'current',
+        released: '2024-01-01',
+        docs: 'https://docs.example.com/api/v2'
+      }
+    ],
+    current: '2',
+    latest: '2'
+  });
+});
+```
+
+### 8. Client SDK Versioning
+
+```typescript
+// client-v1.ts
+export class APIClientV1 {
+  async getUser(id: number): Promise<UserV1> {
+    const response = await fetch(`/api/v1/users/${id}`);
+    return response.json();
+  }
+}
+
+// client-v2.ts
+export class APIClientV2 {
+  async getUser(id: string): Promise<UserV2> {
+    const response = await fetch(`/api/v2/users/${id}`);
+    return response.json();
+  }
+}
+```
+
+### 9. Graceful Degradation
+
+```typescript
+app.get('/api/:version/users/:id', async (req, res) => {
+  const { version, id } = req.params;
+
+  const user = await userService.getUser(id);
+
+  // Format based on version
+  switch (version) {
+    case 'v1':
+      return res.json(formatV1(user));
+    case 'v2':
+      return res.json(formatV2(user));
+    default:
+      // Unknown version - use latest
+      return res.json(formatV2(user));
+  }
+});
+```
+
+### 10. Clear Communication
+
+Announce version changes well in advance:
+
+```markdown
+# API Changelog
+
+## [2.0.0] - 2024-06-01
+
+### Breaking Changes
+- User IDs changed from integers to UUIDs
+- `order_date` field removed, use `created_at` instead
+
+### Added
+- Email field to User resource
+- Pagination support for all list endpoints
+
+### Deprecated
+- V1 API will be sunset on 2025-06-01
+
+## [1.5.0] - 2024-03-01
+
+### Added
+- Search endpoint
+- Bulk operations
+
+### Fixed
+- Date formatting inconsistencies
+```
+
+## Version Header Examples
+
+```typescript
+// Request
+GET /api/users/123
+API-Version: 2
+
+// Response
+HTTP/1.1 200 OK
+API-Version: 2.1.0
+API-Supported-Versions: 1, 2
+API-Deprecated-Versions: 1
+Content-Type: application/json
+
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "Alice",
+  "email": "alice@example.com"
+}
+```