clearctx 3.0.0 → 3.1.0

package/skills/api-design/SKILL.md

@@ -0,0 +1,796 @@
+---
+name: api-design
+description: Production-grade RESTful API design covering resources, status codes, pagination, auth, versioning, and error handling
+domain: api
+keywords: [api, rest, restful, http, endpoints, status-codes, pagination, authentication, openapi]
+version: 1.0.0
+---
+
+# API Design — Expertise Guide
+
+## Worker Context
+
+You are an **API design specialist** for REST APIs. Your role: design clean, consistent, production-grade HTTP endpoints that follow REST principles and modern API best practices.
+
+### Resource Naming
+
+**CRITICAL:** Use plural nouns for resource URLs. NEVER use verbs.
+
+```
+GOOD:
+GET    /users
+POST   /users
+GET    /users/123
+PUT    /users/123
+DELETE /users/123
+
+BAD:
+/getUsers        ❌ verb in URL
+/user            ❌ singular form
+/createNewUser   ❌ verb + inconsistent naming
+```
+
+**Nested resources** (max 2 levels deep):
+```
+GET /users/123/orders           ✅ user's orders
+GET /users/123/orders/456       ✅ specific order
+GET /orders?user_id=123         ✅ alternative, preferred for filtering
+GET /users/123/orders/456/items ❌ too deep (use /order-items/789)
+```
+
+**Multi-word resources:** lowercase with hyphens
+```
+/order-items     ✅
+/orderItems      ❌
+/order_items     ❌
+```
+
+### HTTP Methods
+
+| Method | Purpose | Idempotent | Request Body | Success Code | Use When |
+|--------|---------|------------|--------------|--------------|----------|
+| GET | Read resource(s) | Yes | No | 200 | Fetching data, no side effects |
+| POST | Create new resource | No | Yes | 201 | Creating new records |
+| PUT | Full replacement | Yes | Yes | 200 | Replacing entire resource |
+| PATCH | Partial update | No* | Yes | 200 | Updating specific fields |
+| DELETE | Remove resource | Yes | No | 204 | Deleting records |
+
+*PATCH idempotency depends on implementation — prefer making it idempotent.
+
+**IMPORTANT:** POST creates, PUT replaces entirely (all fields required), PATCH updates partially (only changed fields).
+
+### Status Codes — Exact Usage
+
+**CRITICAL:** Use the correct status code for each scenario. Status codes are semantic contracts.
+
+| Code | Meaning | When to Use | Headers/Body |
+|------|---------|-------------|--------------|
+| 200 | OK | Successful GET, PUT, PATCH | Response body with data |
+| 201 | Created | Successful POST | `Location: /resource/123` header + created resource in body |
+| 204 | No Content | Successful DELETE | Empty body |
+| 400 | Bad Request | Malformed JSON, invalid syntax | Error details |
+| 401 | Unauthorized | Missing or invalid auth token | `WWW-Authenticate` header |
+| 403 | Forbidden | Valid auth but insufficient permissions | Error details |
+| 404 | Not Found | Resource doesn't exist | Error details |
+| 409 | Conflict | Duplicate resource (unique constraint) | Error details with conflict info |
+| 422 | Unprocessable Entity | Valid syntax but semantic errors (validation) | Field-level error details |
+| 429 | Too Many Requests | Rate limit exceeded | `Retry-After` header (seconds) |
+| 500 | Internal Server Error | Unhandled server error | Generic error, NEVER expose internals |
+
+**Decision tree for validation errors:**
+```
+Is the JSON malformed? → 400 Bad Request
+Is a required field missing? → 422 Unprocessable Entity
+Is an email format invalid? → 422 Unprocessable Entity
+Does a username already exist? → 409 Conflict
+```
+
+### Response Envelope
+
+**CRITICAL:** Use consistent response structure across ALL endpoints.
+
+**Success responses:**
+```json
+// Single resource
+{
+  "data": {
+    "id": 123,
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+
+// List (with pagination metadata)
+{
+  "data": [
+    { "id": 1, "name": "Item 1" },
+    { "id": 2, "name": "Item 2" }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 150,
+    "hasNext": true,
+    "nextCursor": "eyJpZCI6MjB9"
+  }
+}
+```
+
+**Error responses:**
+```json
+// Simple error
+{
+  "error": {
+    "code": "RESOURCE_NOT_FOUND",
+    "message": "User with ID 123 not found"
+  }
+}
+
+// Validation errors (422)
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format",
+        "value": "not-an-email"
+      },
+      {
+        "field": "age",
+        "message": "Must be at least 18",
+        "value": 15
+      }
+    ]
+  }
+}
+```
+
+**Error code naming:** `UPPER_SNAKE_CASE`, machine-readable, consistent across API.
+
+**NEVER expose in error responses:**
+- Stack traces
+- SQL queries or database errors
+- Internal file paths
+- Sensitive configuration values
+- Third-party service details
+
+### Pagination
+
+**Prefer cursor-based pagination** (consistent results, no skip-scan overhead):
+```
+GET /users?cursor=eyJpZCI6MjB9&limit=20
+
+Response:
+{
+  "data": [...],
+  "meta": {
+    "limit": 20,
+    "hasNext": true,
+    "nextCursor": "eyJpZCI6NDB9",
+    "prevCursor": "eyJpZCI6MH0"
+  }
+}
+```
+
+**Offset-based acceptable for small datasets** (< 10,000 records):
+```
+GET /users?page=1&limit=20
+
+Response:
+{
+  "data": [...],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8,
+    "hasNext": true
+  }
+}
+```
+
+**IMPORTANT:** Always include `hasNext` boolean. NEVER require clients to calculate page counts.
+
+**Default limit:** 20 items. **Max limit:** 100 items. Reject requests exceeding max with 400.
+
+### Filtering, Sorting, Field Selection
+
+**Query parameters for GET requests** (NEVER use request body for GET):
+
+```
+// Filtering
+GET /users?status=active&role=admin&created_after=2024-01-01
+
+// Sorting (prefix - for descending)
+GET /users?sort=-created_at,name
+// Sorts by created_at DESC, then name ASC
+
+// Field selection (reduce payload size)
+GET /users?fields=id,name,email
+// Returns only specified fields
+
+// Combined
+GET /users?status=active&sort=-created_at&fields=id,name&limit=50
+```
+
+**Filtering conventions:**
+- Exact match: `?status=active`
+- Range: `?created_after=2024-01-01&created_before=2024-12-31`
+- IN clause: `?status=active,pending` (comma-separated)
+- Search: `?q=search+term` (full-text search)
+
+### Versioning
+
+**CRITICAL:** Version your API from day one. Breaking changes require a new version.
+
+**Preferred: URL path versioning**
+```
+/api/v1/users
+/api/v2/users
+```
+
+**Alternative: Header versioning** (cleaner URLs, harder to debug):
+```
+GET /api/users
+Accept: application/vnd.myapi.v1+json
+```
+
+**Breaking changes** (require new major version):
+- Removing fields from responses
+- Changing field types (string → number)
+- Removing endpoints
+- Changing required fields
+- Renaming fields
+
+**Non-breaking changes** (same version):
+- Adding new fields to responses
+- Adding new endpoints
+- Adding optional parameters
+- Adding new enum values (with defaults)
+
+**NEVER:** Change behavior of existing endpoints in-place. Always increment version.
+
+### Authentication & Authorization
+
+**Bearer token auth** (standard for modern APIs):
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+**Response codes:**
+- Missing token → 401 Unauthorized + `WWW-Authenticate: Bearer realm="api"`
+- Expired token → 401 Unauthorized
+- Valid token, insufficient permissions → 403 Forbidden
+
+**Token refresh flow:**
+```
+POST /api/v1/auth/refresh
+Content-Type: application/json
+
+{
+  "refresh_token": "abc123..."
+}
+
+Response 200:
+{
+  "data": {
+    "access_token": "new_token...",
+    "expires_in": 3600,
+    "refresh_token": "new_refresh..."
+  }
+}
+```
+
+**API keys for service-to-service:**
+```
+X-API-Key: sk_live_abc123...
+```
+
+### Rate Limiting
+
+**IMPORTANT:** Include rate limit headers on ALL responses (even successful ones):
+
+```
+X-RateLimit-Limit: 1000        // Max requests per window
+X-RateLimit-Remaining: 847     // Requests left in current window
+X-RateLimit-Reset: 1640000000  // Unix timestamp when limit resets
+```
+
+**When limit exceeded (429):**
+```
+HTTP/1.1 429 Too Many Requests
+Retry-After: 60
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1640000060
+
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "Rate limit exceeded. Retry after 60 seconds."
+  }
+}
+```
+
+### HATEOAS (Hypermedia Links)
+
+**Optional but valuable** for API discoverability:
+
+```json
+{
+  "data": {
+    "id": 123,
+    "name": "John Doe",
+    "status": "active"
+  },
+  "_links": {
+    "self": "/api/v1/users/123",
+    "orders": "/api/v1/users/123/orders",
+    "update": {
+      "href": "/api/v1/users/123",
+      "method": "PUT"
+    },
+    "deactivate": {
+      "href": "/api/v1/users/123/deactivate",
+      "method": "POST"
+    }
+  }
+}
+```
+
+Use `_links` prefix to avoid collision with data fields.
+
+### Idempotency
+
+**CRITICAL for payment/financial APIs:** Support idempotency keys for POST requests.
+
+```
+POST /api/v1/orders
+Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+Content-Type: application/json
+
+{ "amount": 100, "currency": "USD" }
+```
+
+**Server behavior:**
+1. First request with key → process normally, cache response
+2. Duplicate request with same key → return cached response (201)
+3. Key expires after 24 hours
+
+### Request/Response Examples
+
+**Complete POST example:**
+```http
+POST /api/v1/users HTTP/1.1
+Host: api.example.com
+Authorization: Bearer eyJhbGc...
+Content-Type: application/json
+
+{
+  "name": "Jane Doe",
+  "email": "jane@example.com",
+  "role": "editor"
+}
+
+HTTP/1.1 201 Created
+Location: /api/v1/users/456
+Content-Type: application/json
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+
+{
+  "data": {
+    "id": 456,
+    "name": "Jane Doe",
+    "email": "jane@example.com",
+    "role": "editor",
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+**Complete validation error (422):**
+```http
+POST /api/v1/users HTTP/1.1
+Content-Type: application/json
+
+{
+  "name": "",
+  "email": "invalid-email"
+}
+
+HTTP/1.1 422 Unprocessable Entity
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "name",
+        "message": "Name is required and cannot be empty"
+      },
+      {
+        "field": "email",
+        "message": "Email must be a valid email address",
+        "value": "invalid-email"
+      }
+    ]
+  }
+}
+```
+
+## Conventions
+
+**URL structure:**
+- Base: `/api/v{version}/{resource}`
+- Lowercase with hyphens for multi-word: `/order-items`
+- Plural nouns: `/users`, `/products`
+- Max 2 nesting levels: `/users/123/orders`
+
+**Response format:**
+- Success: `{ "data": <result> }` or `{ "data": <result>, "meta": {...} }`
+- Error: `{ "error": { "code": "ERROR_CODE", "message": "...", "details": [...] } }`
+
+**Status code selection:**
+- Read success → 200
+- Create success → 201 + Location header
+- Delete success → 204
+- Validation error → 422 (NOT 400)
+- Duplicate resource → 409
+- Auth missing/invalid → 401
+- Insufficient permissions → 403
+
+**Date/time format:** ISO 8601 with UTC timezone: `2024-01-15T10:30:00Z`
+
+**Boolean values:** `true`/`false` (JSON boolean, not strings)
+
+**Null handling:** Use `null` for missing optional fields. Omit field entirely if appropriate.
+
+**Field naming:** `snake_case` in URLs/query params, match your shared conventions for JSON (typically camelCase for JS, snake_case for Python/Ruby).
+
+## Common Patterns
+
+### Pattern 1: Bulk Operations
+
+**Use case:** Create/update/delete multiple resources in one request.
+
+```http
+POST /api/v1/users/bulk
+{
+  "operations": [
+    { "action": "create", "data": { "name": "User 1", "email": "u1@example.com" } },
+    { "action": "create", "data": { "name": "User 2", "email": "u2@example.com" } }
+  ]
+}
+
+Response 200:
+{
+  "data": {
+    "results": [
+      { "index": 0, "status": "success", "id": 789 },
+      { "index": 1, "status": "error", "error": { "code": "DUPLICATE_EMAIL", "message": "..." } }
+    ],
+    "summary": { "total": 2, "succeeded": 1, "failed": 1 }
+  }
+}
+```
+
+**IMPORTANT:** Return partial success. Don't fail entire batch if one item fails.
+
+### Pattern 2: Async Operations
+
+**Use case:** Long-running operations (report generation, data export, batch processing).
+
+```http
+POST /api/v1/reports
+{ "type": "sales", "start_date": "2024-01-01", "end_date": "2024-01-31" }
+
+Response 202 Accepted:
+{
+  "data": {
+    "job_id": "job_abc123",
+    "status": "pending",
+    "created_at": "2024-01-15T10:30:00Z"
+  },
+  "_links": {
+    "status": "/api/v1/jobs/job_abc123"
+  }
+}
+
+// Check status
+GET /api/v1/jobs/job_abc123
+
+Response 200 (in progress):
+{
+  "data": {
+    "job_id": "job_abc123",
+    "status": "processing",
+    "progress": 45,
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+
+Response 200 (completed):
+{
+  "data": {
+    "job_id": "job_abc123",
+    "status": "completed",
+    "result": { "download_url": "/api/v1/reports/abc123.pdf" },
+    "created_at": "2024-01-15T10:30:00Z",
+    "completed_at": "2024-01-15T10:32:15Z"
+  }
+}
+```
+
+**Status values:** `pending`, `processing`, `completed`, `failed`
+
+### Pattern 3: Soft Delete with Trash
+
+**Use case:** Allow recovery of deleted resources.
+
+```http
+// Soft delete (move to trash)
+DELETE /api/v1/users/123
+Response 204 No Content
+
+// List trashed items
+GET /api/v1/users/trash
+Response 200:
+{
+  "data": [
+    { "id": 123, "name": "John Doe", "deleted_at": "2024-01-15T10:30:00Z" }
+  ]
+}
+
+// Restore
+POST /api/v1/users/123/restore
+Response 200:
+{
+  "data": { "id": 123, "name": "John Doe", "deleted_at": null }
+}
+
+// Permanent delete
+DELETE /api/v1/users/123/permanent
+Response 204 No Content
+```
+
+### Pattern 4: Search Endpoint
+
+**Use case:** Complex search across multiple fields.
+
+```http
+POST /api/v1/search/users
+{
+  "query": "john",
+  "filters": {
+    "status": ["active", "pending"],
+    "created_after": "2024-01-01"
+  },
+  "sort": ["-created_at", "name"],
+  "limit": 20
+}
+
+Response 200:
+{
+  "data": [...],
+  "meta": {
+    "total": 47,
+    "limit": 20,
+    "hasNext": true,
+    "query": "john"
+  }
+}
+```
+
+**Why POST for search?** Complex filter objects don't fit cleanly in query strings. POST /search is acceptable when GET with query params becomes unwieldy.
+
+### Pattern 5: Health & Status Endpoints
+
+**Use case:** Monitoring, load balancer health checks.
+
+```http
+GET /health
+Response 200:
+{
+  "status": "healthy",
+  "version": "1.2.3",
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+
+GET /health/detailed
+Response 200:
+{
+  "status": "healthy",
+  "version": "1.2.3",
+  "checks": {
+    "database": { "status": "healthy", "latency_ms": 12 },
+    "redis": { "status": "healthy", "latency_ms": 3 },
+    "external_api": { "status": "degraded", "latency_ms": 2500 }
+  },
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+**IMPORTANT:** `/health` should be unauthenticated for load balancer access.
+
+## Anti-Patterns
+
+### Anti-Pattern 1: Verbs in Resource URLs ❌
+
+```
+BAD:
+POST /api/v1/createUser
+GET  /api/v1/getUser/123
+POST /api/v1/updateUser/123
+DELETE /api/v1/deleteUser/123
+
+GOOD:
+POST   /api/v1/users
+GET    /api/v1/users/123
+PUT    /api/v1/users/123
+DELETE /api/v1/users/123
+```
+
+**Why it's bad:** Violates REST principles. HTTP method already expresses the action.
+
+### Anti-Pattern 2: Inconsistent Plural/Singular Mixing ❌
+
+```
+BAD:
+GET /api/v1/user/123        ❌ singular
+GET /api/v1/products        ✅ plural
+GET /api/v1/order/456       ❌ singular
+GET /api/v1/customers       ✅ plural
+
+GOOD:
+GET /api/v1/users/123       ✅ all plural
+GET /api/v1/products        ✅
+GET /api/v1/orders/456      ✅
+GET /api/v1/customers       ✅
+```
+
+**Why it's bad:** Forces clients to memorize which resources are plural vs singular. Cognitive overhead.
+
+### Anti-Pattern 3: Using 200 for All Responses ❌
+
+```
+BAD:
+POST /api/v1/users
+Response 200:
+{
+  "status": "success",
+  "data": { "id": 123, ... }
+}
+
+DELETE /api/v1/users/123
+Response 200:
+{
+  "status": "success",
+  "message": "User deleted"
+}
+
+GET /api/v1/users/999
+Response 200:
+{
+  "status": "error",
+  "message": "User not found"
+}
+
+GOOD:
+POST /api/v1/users → 201 Created
+DELETE /api/v1/users/123 → 204 No Content
+GET /api/v1/users/999 → 404 Not Found
+```
+
+**Why it's bad:** HTTP status codes ARE the status. Duplicating them in the body is redundant and breaks HTTP semantics. Clients can't rely on status codes.
+
+### Anti-Pattern 4: No Pagination on List Endpoints ❌
+
+```
+BAD:
+GET /api/v1/users
+// Returns ALL users (10,000+ records)
+
+GOOD:
+GET /api/v1/users?limit=20
+// Returns paginated results with meta.hasNext
+```
+
+**Why it's bad:** Kills performance, timeouts, memory issues. ALWAYS paginate list endpoints.
+
+### Anti-Pattern 5: Exposing Internal Implementation in Errors ❌
+
+```
+BAD:
+Response 500:
+{
+  "error": {
+    "message": "SQLException: Duplicate entry 'john@example.com' for key 'users.email'",
+    "stack": "at Database.query (/var/www/app/db.js:45:12)..."
+  }
+}
+
+GOOD:
+Response 409:
+{
+  "error": {
+    "code": "DUPLICATE_EMAIL",
+    "message": "A user with this email already exists"
+  }
+}
+```
+
+**Why it's bad:** Security risk (exposes database structure, file paths). Ugly for consumers. Use semantic error codes.
+
+## Integration Notes
+
+**Multi-session orchestration context:**
+
+1. **Check inbox before starting:**
+   ```javascript
+   // Always first action
+   await mcp.team_check_inbox({ name: "api-dev" })
+   ```
+
+2. **Read shared conventions:**
+   ```javascript
+   const conventions = await mcp.artifact_get({
+     artifactId: "shared-conventions",
+     reader: "api-dev"
+   })
+   // Use conventions.data.responseFormat, .statusCodes, .enumValues, etc.
+   ```
+
+3. **Coordinate with DB worker:**
+   - Resource names must match table names (plural form)
+   - Use exact enum values from DB schema
+   - Align on `snake_case` vs `camelCase` for JSON fields
+   - Ask DB worker for foreign key constraints before designing nested resources
+
+4. **Publish API contract artifact:**
+   ```javascript
+   await mcp.artifact_publish({
+     artifactId: "api-contract",
+     type: "api-contract",
+     name: "REST API Contract v1",
+     publisher: "api-dev",
+     data: {
+       version: "v1",
+       baseUrl: "/api/v1",
+       endpoints: [
+         {
+           path: "/users",
+           methods: ["GET", "POST"],
+           auth: "required",
+           request: { /* schema */ },
+           response: { /* schema */ }
+         }
+         // ... all endpoints
+       ],
+       statusCodes: { /* map of codes to meanings */ },
+       errorCodes: ["VALIDATION_ERROR", "DUPLICATE_EMAIL", ...]
+     }
+   })
+   ```
+
+5. **Broadcast completion:**
+   ```javascript
+   await mcp.team_broadcast({
+     from: "api-dev",
+     content: "API contract published with 12 endpoints. All workers: read artifact 'api-contract' for request/response schemas and status codes."
+   })
+   ```
+
+6. **File paths:** Use relative paths only (`src/routes/users.js`, NOT `/home/user/project/src/routes/users.js`)
+
+7. **Consumed by:** Frontend workers (React, mobile apps) use this artifact to generate API client code and TypeScript types. Backend workers implement the contract.
+
+8. **Team communication:**
+   - If DB schema is unclear → `team_ask({ to: "db-dev", question: "What's the exact enum for user.status?" })`
+   - If frontend needs custom endpoint → they message you, you update contract, republish artifact
+
+**Work autonomously:** Use shared conventions + DB schema. Only ask teammates when you hit genuine ambiguity (conflicting requirements, missing specs).