codeforge-dev 1.7.0 → 1.9.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/api-design/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: api-design
+description: >-
+  This skill should be used when the user asks to "design an API",
+  "design REST endpoints", "plan API versioning", "choose pagination strategy",
+  "design error responses", "API conventions", "endpoint design",
+  "create API documentation", or discusses REST API design, HTTP method
+  semantics, status code selection, authentication patterns, or rate limiting.
+version: 0.1.0
+---
+
+# API Design
+
+## Mental Model
+
+APIs are **contracts**. Once published, they are promises to consumers. Design for the consumer, not the implementation. Consistency beats cleverness — a predictable API with simple conventions is easier to use than a clever API with special cases.
+
+**Key principles:**
+- **Resources, not actions.** URLs name things (`/users`, `/orders`), HTTP methods express actions (GET, POST, PUT, DELETE). Verbs in URLs signal a design problem.
+- **Consistency above all.** If one endpoint uses `snake_case`, all endpoints use `snake_case`. If one endpoint paginates with `cursor`, all endpoints paginate with `cursor`.
+- **Explicit over implicit.** Document every behavior. Default values, sort orders, pagination limits — if a consumer has to guess, the API is underspecified.
+- **Idempotency by design.** GET, PUT, DELETE are idempotent. POST creates new resources. Design operations so repeating a request does not produce unexpected side effects.
+
+---
+
+## Resource Naming
+
+Use plural nouns for collections, singular identifiers for individual resources:
+
+```
+GET    /users          → List users
+POST   /users          → Create a user
+GET    /users/{id}     → Get a specific user
+PUT    /users/{id}     → Replace a user
+PATCH  /users/{id}     → Partially update a user
+DELETE /users/{id}     → Delete a user
+```
+
+**Nested resources** for clear ownership:
+```
+GET    /users/{id}/orders       → List orders for a user
+POST   /users/{id}/orders       → Create an order for a user
+GET    /users/{id}/orders/{oid} → Get a specific order
+```
+
+Limit nesting to 2 levels. Beyond that, promote the resource to a top-level endpoint with a query filter: `/orders?user_id=123`.
+
+**Naming rules:**
+- Use `kebab-case` for multi-word paths: `/order-items`, not `/orderItems`
+- Use `snake_case` for query parameters: `?sort_by=created_at`
+- Use `snake_case` for JSON fields (aligns with Python/Ruby; for JavaScript-heavy APIs, `camelCase` is also acceptable — pick one and be consistent)
+
+---
+
+## HTTP Method Semantics
+
+| Method | Purpose | Idempotent | Request Body | Success Code |
+|--------|---------|-----------|-------------|-------------|
+| **GET** | Read resource(s) | Yes | No | 200 |
+| **POST** | Create resource | No | Yes | 201 |
+| **PUT** | Full replace | Yes | Yes | 200 |
+| **PATCH** | Partial update | No* | Yes | 200 |
+| **DELETE** | Remove resource | Yes | No | 204 |
+| **HEAD** | Headers only (like GET) | Yes | No | 200 |
+| **OPTIONS** | Describe capabilities | Yes | No | 204 |
+
+*PATCH is idempotent if using JSON Merge Patch; not idempotent with JSON Patch operations.
+
+---
+
+## Pagination Patterns
+
+### Cursor-Based (Recommended)
+
+Best for real-time data, large datasets, and stable traversal:
+
+```json
+GET /users?cursor=eyJpZCI6MTIzfQ&limit=20
+
+{
+  "data": [...],
+  "pagination": {
+    "next_cursor": "eyJpZCI6MTQzfQ",
+    "has_more": true
+  }
+}
+```
+
+Cursors are opaque tokens (base64-encoded state). Consumers pass them back unchanged.
+
+### Offset-Based
+
+Simpler but unstable under concurrent writes:
+
+```json
+GET /users?offset=40&limit=20
+
+{
+  "data": [...],
+  "pagination": {
+    "offset": 40,
+    "limit": 20,
+    "total": 156
+  }
+}
+```
+
+### Decision Framework
+
+| Factor | Cursor | Offset |
+|--------|--------|--------|
+| Data stability | Handles inserts/deletes during pagination | Rows shift when data changes |
+| Performance at scale | O(1) per page | O(n) for large offsets |
+| "Jump to page N" | Not supported | Supported |
+| Implementation complexity | Higher | Lower |
+
+**Default**: Cursor pagination for new APIs. Offset only when consumers explicitly need page-number navigation.
+
+---
+
+## Versioning
+
+### URL Path Versioning (Recommended)
+
+```
+/v1/users
+/v2/users
+```
+
+Visible in every request. Easy to route, test, and document. Most widely understood.
+
+### Header Versioning
+
+```
+Accept: application/vnd.api+json; version=2
+```
+
+Cleaner URLs but harder to test (can't bookmark/share versioned URLs) and harder to route.
+
+### Decision Framework
+
+| Factor | URL Path | Header |
+|--------|----------|--------|
+| Discoverability | High — visible in URL | Low — hidden in headers |
+| Cacheability | Easy — URL-based caching | Requires Vary header |
+| Testing | Easy — curl/browser | Requires setting headers |
+| Aesthetics | "Ugly" URLs | Clean URLs |
+
+**Default**: URL path versioning. It is the most pragmatic choice for most APIs.
+
+---
+
+## Authentication Patterns
+
+| Pattern | Best For | Considerations |
+|---------|----------|---------------|
+| **API Keys** | Server-to-server, simple integrations | Easy to implement. No expiry by default — rotate regularly. Send via header (`X-API-Key` or `Authorization: Bearer`), never in URL. |
+| **JWT (Bearer Tokens)** | Stateless auth, microservices | Self-contained claims. Set short expiry (15-60 min) + refresh tokens. Verify signature and expiry on every request. |
+| **OAuth 2.0** | Third-party integrations, user consent | Authorization Code flow for web apps, Client Credentials for machine-to-machine. Use PKCE for public clients. |
+| **Session Cookies** | Browser-based web apps | Set `HttpOnly`, `Secure`, `SameSite=Strict`. CSRF protection required. |
+
+**Default**: JWT for APIs consumed by multiple clients. API keys for simple server-to-server integrations.
+
+---
+
+## Rate Limiting
+
+### Token Bucket (Recommended)
+
+Allows bursts up to bucket size, then enforces sustained rate:
+- Bucket holds N tokens (e.g., 100)
+- Tokens refill at R per second (e.g., 10/s)
+- Each request costs 1 token (or more for expensive operations)
+
+### Response Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 42
+X-RateLimit-Reset: 1640000000
+Retry-After: 30
+```
+
+Return `429 Too Many Requests` with `Retry-After` header when limit is exceeded.
+
+---
+
+## API Design Checklist
+
+Before implementing, verify:
+
+- [ ] Every endpoint uses a plural noun (not a verb) in the URL
+- [ ] HTTP methods match their semantic purpose
+- [ ] Response format is consistent across all endpoints
+- [ ] Error responses follow a standard format (see reference)
+- [ ] Pagination strategy is consistent across all list endpoints
+- [ ] Authentication mechanism is documented
+- [ ] Rate limits are defined and communicated via headers
+- [ ] Versioning strategy is chosen and applied
+- [ ] All parameters have documented types, constraints, and defaults
+- [ ] Idempotency behavior is documented for each endpoint
+
+---
+
+## Ambiguity Policy
+
+| Ambiguity | Default |
+|-----------|---------|
+| **API style** | REST with JSON request/response bodies |
+| **Pagination** | Cursor-based with `limit` parameter (default 20, max 100) |
+| **Versioning** | URL path versioning (`/v1/`) |
+| **Naming convention** | `snake_case` for JSON fields, `kebab-case` for URL paths |
+| **Auth pattern** | JWT Bearer tokens (unless server-to-server, then API keys) |
+| **Error format** | RFC 7807 Problem Details |
+| **Rate limiting** | Token bucket with standard headers |
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [REST Conventions](references/rest-conventions.md) | Complete HTTP method semantics, status code reference by category, resource naming examples, query parameter patterns, content negotiation, and HATEOAS guidance |
+| [Error Handling](references/error-handling.md) | RFC 7807 Problem Details format, error code taxonomy, consistency rules, client-vs-server error exposure, and retry guidance headers |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/api-design/references/error-handling.md

@@ -0,0 +1,166 @@
+# API Error Handling Reference
+
+## RFC 7807 Problem Details
+
+The standard format for HTTP API error responses. Use `application/problem+json` as the content type.
+
+### Format
+
+```json
+{
+  "type": "https://api.example.com/errors/validation-error",
+  "title": "Validation Error",
+  "status": 422,
+  "detail": "The 'email' field must be a valid email address.",
+  "instance": "/users/signup",
+  "errors": [
+    {
+      "field": "email",
+      "message": "Must be a valid email address",
+      "value": "not-an-email"
+    }
+  ]
+}
+```
+
+### Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | URI reference identifying the error type. Use a stable URL (can be a documentation page). |
+| `title` | Yes | Short human-readable summary. Same for all instances of this error type. |
+| `status` | Yes | HTTP status code (repeated from response for convenience). |
+| `detail` | Yes | Human-readable explanation specific to this occurrence. |
+| `instance` | No | URI identifying the specific occurrence (request path or trace ID). |
+
+Extension fields (like `errors` for validation) are allowed and encouraged for structured detail.
+
+---
+
+## Error Code Taxonomy
+
+Organize errors into categories with consistent type URIs:
+
+### Validation Errors (400 / 422)
+
+```json
+{
+  "type": "https://api.example.com/errors/validation-error",
+  "title": "Validation Error",
+  "status": 422,
+  "detail": "Request body contains invalid fields.",
+  "errors": [
+    { "field": "email", "message": "Required field is missing" },
+    { "field": "age", "message": "Must be a positive integer", "value": -5 }
+  ]
+}
+```
+
+Use `422` for semantic validation failures (valid JSON but invalid data). Use `400` for malformed requests (invalid JSON, wrong content type).
+
+### Authentication Errors (401)
+
+```json
+{
+  "type": "https://api.example.com/errors/authentication-required",
+  "title": "Authentication Required",
+  "status": 401,
+  "detail": "The access token has expired. Request a new token."
+}
+```
+
+Always include `WWW-Authenticate` header with 401 responses.
+
+### Authorization Errors (403)
+
+```json
+{
+  "type": "https://api.example.com/errors/insufficient-permissions",
+  "title": "Insufficient Permissions",
+  "status": 403,
+  "detail": "Your API key does not have access to the 'admin' scope."
+}
+```
+
+### Not Found (404)
+
+```json
+{
+  "type": "https://api.example.com/errors/resource-not-found",
+  "title": "Resource Not Found",
+  "status": 404,
+  "detail": "No user found with ID '999'."
+}
+```
+
+### Conflict (409)
+
+```json
+{
+  "type": "https://api.example.com/errors/resource-conflict",
+  "title": "Resource Conflict",
+  "status": 409,
+  "detail": "A user with email 'jane@example.com' already exists."
+}
+```
+
+### Rate Limit (429)
+
+```json
+{
+  "type": "https://api.example.com/errors/rate-limit-exceeded",
+  "title": "Rate Limit Exceeded",
+  "status": 429,
+  "detail": "You have exceeded 100 requests per minute. Try again in 30 seconds."
+}
+```
+
+Always include `Retry-After` header (seconds or HTTP-date).
+
+### Internal Error (500)
+
+```json
+{
+  "type": "https://api.example.com/errors/internal-error",
+  "title": "Internal Server Error",
+  "status": 500,
+  "detail": "An unexpected error occurred. Reference: trace-abc123."
+}
+```
+
+---
+
+## Error Response Consistency Rules
+
+1. **Same shape, always.** Every error response uses the same top-level structure. Consumers should never need to handle different error formats.
+2. **Match status code to error.** The `status` field in the body matches the HTTP status code. Never return `200 OK` with an error body.
+3. **Human-readable details.** The `detail` field should help the consumer fix the problem. "Invalid request" is useless. "The 'email' field must be a valid email address" is actionable.
+4. **Machine-readable type.** The `type` URI enables programmatic error handling. Consumers can switch on the type without parsing the detail string.
+5. **No stack traces in production.** Internal error details (stack traces, database errors, internal paths) are logged server-side. Clients receive a reference ID to correlate with server logs.
+
+---
+
+## Error Logging vs. Error Exposure
+
+| Information | Log Server-Side | Return to Client |
+|-------------|----------------|-----------------|
+| Stack trace | Yes | No |
+| Database error messages | Yes | No |
+| Internal file paths | Yes | No |
+| Request ID / trace ID | Yes | Yes (in `instance` or `detail`) |
+| Validation errors | Yes | Yes (specific field-level errors) |
+| Rate limit status | Yes | Yes (via headers + body) |
+| Business rule violations | Yes | Yes (as actionable `detail`) |
+
+---
+
+## Retry Guidance Headers
+
+| Header | Purpose | Format |
+|--------|---------|--------|
+| `Retry-After` | When to retry after 429 or 503 | Seconds (`30`) or HTTP-date (`Wed, 21 Oct 2025 07:28:00 GMT`) |
+| `X-RateLimit-Limit` | Maximum requests allowed in window | Integer (`100`) |
+| `X-RateLimit-Remaining` | Requests remaining in current window | Integer (`42`) |
+| `X-RateLimit-Reset` | Unix timestamp when window resets | Integer (`1640000000`) |
+
+Include all rate limit headers on **every response** (not just 429s) so clients can proactively manage their request rate.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/api-design/references/rest-conventions.md

@@ -0,0 +1,215 @@
+# REST Conventions Reference
+
+## HTTP Method Semantics
+
+### GET — Read Resources
+
+- Retrieves a resource or collection. Never modifies state.
+- **Cacheable** by default. Use `Cache-Control` and `ETag` headers.
+- Collection: `GET /users` → `200 OK` with array
+- Single: `GET /users/123` → `200 OK` with object, or `404 Not Found`
+
+### POST — Create Resources
+
+- Creates a new resource. The server assigns the ID.
+- **Not idempotent** — repeating the request creates duplicate resources.
+- Response: `201 Created` with `Location` header pointing to the new resource.
+- Include the created resource in the response body.
+
+### PUT — Full Replace
+
+- Replaces the entire resource. Client sends the complete representation.
+- **Idempotent** — repeating the request produces the same state.
+- If the resource doesn't exist: return `404` (don't auto-create unless designed for upsert).
+- Response: `200 OK` with the updated resource.
+
+### PATCH — Partial Update
+
+- Modifies specific fields without replacing the entire resource.
+- Use JSON Merge Patch (`Content-Type: application/merge-patch+json`) for simplicity.
+- Response: `200 OK` with the complete updated resource.
+- Omitted fields remain unchanged.
+
+### DELETE — Remove Resources
+
+- Removes a resource.
+- **Idempotent** — deleting an already-deleted resource returns `204` or `404` (both are valid, be consistent).
+- Response: `204 No Content` (no body).
+
+### HEAD — Headers Only
+
+- Identical to GET but returns no body. Used for checking existence, content length, or cache validity.
+
+### OPTIONS — Capabilities
+
+- Returns allowed methods and CORS headers. Response: `204 No Content` with `Allow` header.
+
+---
+
+## Status Code Reference
+
+### 2xx — Success
+
+| Code | Name | When to Use |
+|------|------|------------|
+| `200` | OK | GET, PUT, PATCH succeeded. General success. |
+| `201` | Created | POST created a resource. Include `Location` header. |
+| `202` | Accepted | Request accepted for async processing. Include status URL. |
+| `204` | No Content | DELETE succeeded. OPTIONS response. No body. |
+
+### 3xx — Redirection
+
+| Code | Name | When to Use |
+|------|------|------------|
+| `301` | Moved Permanently | Resource URL changed permanently. Clients should update. |
+| `302` | Found | Temporary redirect. Original URL still valid. |
+| `304` | Not Modified | Cache is still valid. Response to conditional GET. |
+
+### 4xx — Client Errors
+
+| Code | Name | When to Use |
+|------|------|------------|
+| `400` | Bad Request | Malformed syntax, invalid JSON, missing required fields. |
+| `401` | Unauthorized | No credentials or invalid/expired credentials. |
+| `403` | Forbidden | Valid credentials but insufficient permissions. |
+| `404` | Not Found | Resource doesn't exist. |
+| `405` | Method Not Allowed | HTTP method not supported for this URL. Include `Allow` header. |
+| `409` | Conflict | State conflict (duplicate, version mismatch, concurrent modification). |
+| `410` | Gone | Resource existed but was permanently deleted. |
+| `415` | Unsupported Media Type | Content-Type not supported. |
+| `422` | Unprocessable Entity | Valid syntax but semantic errors (validation failures). |
+| `429` | Too Many Requests | Rate limit exceeded. Include `Retry-After` header. |
+
+### 5xx — Server Errors
+
+| Code | Name | When to Use |
+|------|------|------------|
+| `500` | Internal Server Error | Unhandled exception. Log the error, return generic message. |
+| `502` | Bad Gateway | Upstream service returned invalid response. |
+| `503` | Service Unavailable | Server overloaded or in maintenance. Include `Retry-After`. |
+| `504` | Gateway Timeout | Upstream service did not respond in time. |
+
+---
+
+## Resource Naming Conventions
+
+### Collection Patterns
+
+```
+/users                    → User collection
+/users/{id}               → Specific user
+/users/{id}/orders        → Orders belonging to a user
+/users/{id}/orders/{oid}  → Specific order of a user
+```
+
+### Naming Rules
+
+- **Plural nouns** for collections: `/users`, not `/user`
+- **Lowercase with hyphens** for multi-word: `/order-items`, not `/orderItems` or `/order_items`
+- **No trailing slashes**: `/users`, not `/users/`
+- **No file extensions**: `/users/123`, not `/users/123.json`
+- **No verbs**: `/users/{id}/activate` is acceptable as an action endpoint (RPC-style), but prefer state changes via PATCH when possible
+
+### Action Endpoints (RPC-Style)
+
+When a RESTful mapping is awkward, use action sub-resources:
+
+```
+POST /users/{id}/activate     → Activate a user
+POST /orders/{id}/cancel      → Cancel an order
+POST /emails/{id}/resend      → Resend an email
+```
+
+Action endpoints are always POST (they change state and are not idempotent).
+
+---
+
+## Query Parameter Patterns
+
+### Filtering
+
+```
+GET /users?status=active
+GET /users?role=admin&status=active
+GET /orders?created_after=2024-01-01&created_before=2024-12-31
+```
+
+Use `snake_case` for parameter names. Support multiple values with comma separation or repeated params:
+```
+GET /users?role=admin,editor       (comma-separated)
+GET /users?role=admin&role=editor  (repeated)
+```
+
+### Sorting
+
+```
+GET /users?sort_by=created_at&sort_order=desc
+GET /users?sort=-created_at,name   (prefix - for descending)
+```
+
+### Field Selection
+
+```
+GET /users?fields=id,name,email
+GET /users/{id}?fields=id,name,email,orders
+```
+
+Reduces payload size. Particularly valuable for mobile clients or list views.
+
+### Search
+
+```
+GET /users?q=john                     (full-text search)
+GET /users?name_contains=john         (field-specific search)
+```
+
+---
+
+## Content Negotiation
+
+### Request Headers
+
+```
+Content-Type: application/json        → Request body format
+Accept: application/json              → Desired response format
+Accept-Language: en-US                → Preferred language
+```
+
+### Response Headers
+
+```
+Content-Type: application/json; charset=utf-8
+Content-Length: 1234
+ETag: "abc123"
+Cache-Control: max-age=3600
+```
+
+### Versioned Media Types
+
+```
+Accept: application/vnd.myapi.v2+json
+```
+
+An alternative to URL path versioning. The server reads the Accept header to determine which version to serve.
+
+---
+
+## HATEOAS (Hypermedia)
+
+Include links to related resources and actions in responses:
+
+```json
+{
+  "id": 123,
+  "name": "Jane Doe",
+  "links": {
+    "self": "/users/123",
+    "orders": "/users/123/orders",
+    "activate": "/users/123/activate"
+  }
+}
+```
+
+**When it is worth it**: Public APIs consumed by many third-party clients. The links enable discoverability without hardcoding URL patterns.
+
+**When it is over-engineering**: Internal APIs where clients are maintained by the same team. The added payload and complexity rarely justify the benefit.