@cubis/foundry 0.3.63 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/api-designer/references/rest-patterns.md

@@ -0,0 +1,335 @@
+# REST Design Patterns
+
+## Resource-Oriented Architecture
+
+REST APIs are built around resources, not actions. Resources are the nouns of your API.
+
+### Resource Identification
+
+**Good Resource URIs:**
+```
+GET    /users                  # Collection
+GET    /users/{id}             # Individual resource
+GET    /users/{id}/orders      # Nested collection
+POST   /users                  # Create resource
+PUT    /users/{id}             # Replace resource
+PATCH  /users/{id}             # Update resource
+DELETE /users/{id}             # Delete resource
+```
+
+**Bad Resource URIs:**
+```
+POST   /getUser                # Verb in URI
+POST   /createUser             # Verb in URI
+GET    /user?action=delete     # Action as query param
+```
+
+### Resource Naming Conventions
+
+- Use plural nouns for collections: `/users`, `/orders`, `/products`
+- Use lowercase and hyphens for readability: `/shipping-addresses`
+- Avoid deep nesting (max 2-3 levels): `/users/{id}/orders/{orderId}`
+- Use query parameters for filtering: `/users?status=active&role=admin`
+
+## HTTP Method Semantics
+
+### Safe and Idempotent Methods
+
+| Method | Safe | Idempotent | Use Case |
+|--------|------|------------|----------|
+| GET | Yes | Yes | Retrieve resource(s) |
+| POST | No | No | Create resource, non-idempotent operations |
+| PUT | No | Yes | Replace entire resource |
+| PATCH | No | No | Partial update |
+| DELETE | No | Yes | Remove resource |
+| HEAD | Yes | Yes | Get metadata only |
+| OPTIONS | Yes | Yes | Get allowed methods |
+
+### Method Usage
+
+**GET - Retrieve Resources**
+```http
+GET /users/123
+Accept: application/json
+
+Response: 200 OK
+{
+  "id": 123,
+  "name": "John Doe",
+  "email": "john@example.com",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+**POST - Create Resources**
+```http
+POST /users
+Content-Type: application/json
+
+{
+  "name": "Jane Smith",
+  "email": "jane@example.com"
+}
+
+Response: 201 Created
+Location: /users/124
+{
+  "id": 124,
+  "name": "Jane Smith",
+  "email": "jane@example.com",
+  "created_at": "2024-01-16T14:20:00Z"
+}
+```
+
+**PUT - Replace Resource**
+```http
+PUT /users/123
+Content-Type: application/json
+
+{
+  "name": "John Doe Updated",
+  "email": "john.new@example.com"
+}
+
+Response: 200 OK
+{
+  "id": 123,
+  "name": "John Doe Updated",
+  "email": "john.new@example.com",
+  "updated_at": "2024-01-17T09:15:00Z"
+}
+```
+
+**PATCH - Partial Update**
+```http
+PATCH /users/123
+Content-Type: application/json
+
+{
+  "email": "john.updated@example.com"
+}
+
+Response: 200 OK
+{
+  "id": 123,
+  "name": "John Doe",
+  "email": "john.updated@example.com",
+  "updated_at": "2024-01-17T10:00:00Z"
+}
+```
+
+**DELETE - Remove Resource**
+```http
+DELETE /users/123
+
+Response: 204 No Content
+```
+
+## HTTP Status Codes
+
+### Success Codes (2xx)
+
+- **200 OK** - Request succeeded (GET, PUT, PATCH)
+- **201 Created** - Resource created (POST), include Location header
+- **202 Accepted** - Request accepted for async processing
+- **204 No Content** - Success with no response body (DELETE)
+
+### Redirection (3xx)
+
+- **301 Moved Permanently** - Resource permanently moved
+- **302 Found** - Temporary redirect
+- **304 Not Modified** - Cached version is still valid
+
+### Client Errors (4xx)
+
+- **400 Bad Request** - Invalid request syntax or validation error
+- **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 for resource
+- **409 Conflict** - Request conflicts with current state (e.g., duplicate)
+- **422 Unprocessable Entity** - Valid syntax but semantic 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 server
+- **503 Service Unavailable** - Server temporarily unavailable
+- **504 Gateway Timeout** - Upstream server timeout
+
+## HATEOAS (Hypermedia)
+
+### Hypermedia-Driven APIs
+
+Include links to related resources and available actions:
+
+```json
+{
+  "id": 123,
+  "name": "John Doe",
+  "email": "john@example.com",
+  "_links": {
+    "self": { "href": "/users/123" },
+    "orders": { "href": "/users/123/orders" },
+    "update": { "href": "/users/123", "method": "PATCH" },
+    "delete": { "href": "/users/123", "method": "DELETE" }
+  }
+}
+```
+
+### HAL (Hypertext Application Language)
+
+```json
+{
+  "id": 123,
+  "name": "John Doe",
+  "_links": {
+    "self": { "href": "/users/123" }
+  },
+  "_embedded": {
+    "orders": [
+      {
+        "id": 456,
+        "total": 99.99,
+        "_links": {
+          "self": { "href": "/orders/456" }
+        }
+      }
+    ]
+  }
+}
+```
+
+## Content Negotiation
+
+### Accept Headers
+
+```http
+GET /users/123
+Accept: application/json
+
+GET /users/123
+Accept: application/xml
+
+GET /users/123
+Accept: application/hal+json
+```
+
+### Response Content-Type
+
+```http
+Content-Type: application/json; charset=utf-8
+Content-Type: application/problem+json
+Content-Type: application/hal+json
+```
+
+## Idempotency
+
+### Idempotent Operations
+
+**PUT - Always idempotent:**
+Multiple identical PUT requests produce the same result as a single request.
+
+**DELETE - Idempotent:**
+First DELETE returns 204, subsequent DELETEs return 404 (same end state).
+
+**POST - Not idempotent by default:**
+Use `Idempotency-Key` header for idempotent POST:
+
+```http
+POST /payments
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+Content-Type: application/json
+
+{
+  "amount": 100.00,
+  "currency": "USD"
+}
+```
+
+Server stores idempotency key and returns same response for duplicate requests.
+
+## Cache Control
+
+### Cache Headers
+
+```http
+Cache-Control: public, max-age=3600
+Cache-Control: private, no-cache
+Cache-Control: no-store
+ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
+Last-Modified: Wed, 15 Jan 2024 10:30:00 GMT
+```
+
+### Conditional Requests
+
+```http
+GET /users/123
+If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
+
+Response: 304 Not Modified
+```
+
+```http
+PUT /users/123
+If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
+Content-Type: application/json
+
+{
+  "name": "Updated Name"
+}
+
+Response: 412 Precondition Failed (if ETag doesn't match)
+```
+
+## URI Patterns
+
+### Consistent URI Structure
+
+```
+/{version}/{resource}
+/{version}/{resource}/{id}
+/{version}/{resource}/{id}/{sub-resource}
+/{version}/{resource}/{id}/{sub-resource}/{sub-id}
+```
+
+### Query Parameters
+
+**Filtering:**
+```
+GET /users?status=active&role=admin
+GET /products?category=electronics&price_min=100&price_max=500
+```
+
+**Sorting:**
+```
+GET /users?sort=created_at
+GET /users?sort=-created_at          # Descending
+GET /users?sort=name,created_at      # Multiple fields
+```
+
+**Field Selection:**
+```
+GET /users?fields=id,name,email
+GET /users?exclude=password,social_security_number
+```
+
+**Search:**
+```
+GET /users?q=john
+GET /products?search=laptop
+```
+
+## Best Practices
+
+1. **Use nouns, not verbs** - Resources are nouns, methods are verbs
+2. **Plural collections** - Use `/users` not `/user`
+3. **Consistent naming** - Choose snake_case or camelCase and stick to it
+4. **Proper status codes** - Use appropriate HTTP status codes
+5. **Include metadata** - Pagination, filtering, sorting info in responses
+6. **Version your API** - Plan for evolution from day one
+7. **Document everything** - OpenAPI specs, examples, error codes
+8. **Security by default** - HTTPS, authentication, rate limiting
+9. **Support filtering** - Enable clients to get exactly what they need
+10. **Implement HATEOAS** - Make APIs self-documenting and discoverable

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/api-designer/references/versioning.md

@@ -0,0 +1,391 @@
+# API Versioning Strategies
+
+## Why Version APIs?
+
+API versioning allows you to evolve your API while maintaining backward compatibility for existing clients. Breaking changes require a new version.
+
+### Breaking Changes
+
+Changes that require a new version:
+- Removing or renaming fields
+- Changing field types (string to integer)
+- Adding required fields to requests
+- Changing response structure
+- Removing endpoints
+- Changing HTTP status codes for same scenario
+- Changing authentication mechanisms
+
+### Non-Breaking Changes
+
+Safe changes that don't require a new version:
+- Adding new endpoints
+- Adding optional request fields
+- Adding new fields to responses (clients should ignore unknown fields)
+- Fixing bugs
+- Performance improvements
+- Adding new HTTP methods to existing resources
+
+## Versioning Strategies
+
+### 1. URI Versioning
+
+Most common and visible approach. Version is part of the URL path.
+
+```http
+GET /v1/users/123
+GET /v2/users/123
+```
+
+**Advantages:**
+- Clear and visible in URLs
+- Easy to understand and implement
+- Simple routing and caching
+- Can run multiple versions simultaneously
+
+**Disadvantages:**
+- Violates REST principle (same resource, different URIs)
+- Requires updating client code to change version
+- Can lead to URI proliferation
+
+**Implementation:**
+```
+/v1/users
+/v1/products
+/v2/users      # New version with breaking changes
+/v2/products
+```
+
+### 2. Header Versioning
+
+Version specified in HTTP headers (Accept header or custom header).
+
+**Accept Header:**
+```http
+GET /users/123
+Accept: application/vnd.myapi.v1+json
+
+GET /users/123
+Accept: application/vnd.myapi.v2+json
+```
+
+**Custom Header:**
+```http
+GET /users/123
+API-Version: 1
+
+GET /users/123
+API-Version: 2
+```
+
+**Advantages:**
+- URIs remain stable
+- More RESTful (same resource, same URI)
+- Separates versioning from resource identification
+
+**Disadvantages:**
+- Less visible (harder to debug)
+- More complex routing
+- Difficult to test in browser
+- Cache complexity
+
+### 3. Query Parameter Versioning
+
+Version specified as query parameter.
+
+```http
+GET /users/123?version=1
+GET /users/123?version=2
+
+# or
+GET /users/123?api-version=1
+GET /users/123?api-version=2
+```
+
+**Advantages:**
+- Simple to implement
+- Easy to test
+- Visible in URLs
+
+**Disadvantages:**
+- Pollutes query string
+- Not semantic (version not a filter)
+- Can interfere with other query params
+
+### 4. Content Negotiation
+
+Client specifies desired version through content negotiation.
+
+```http
+GET /users/123
+Accept: application/vnd.myapi+json; version=1
+
+GET /users/123
+Accept: application/vnd.myapi+json; version=2
+```
+
+**Advantages:**
+- Very RESTful
+- Flexible content type negotiation
+- Stable URIs
+
+**Disadvantages:**
+- Complex implementation
+- Less intuitive for developers
+- Harder to test
+
+## Recommended Approach
+
+**URI versioning is recommended for most APIs** because:
+- It's the most explicit and discoverable
+- Easy to understand and debug
+- Simple to implement and maintain
+- Clear separation between versions
+
+```
+/v1/users
+/v2/users
+/v3/users
+```
+
+## Version Format
+
+### Major Versions Only
+
+Use simple major versions (v1, v2, v3) for public APIs:
+```
+/v1/users
+/v2/users
+```
+
+**Advantages:**
+- Simple and clear
+- Easy to communicate
+- Forces thoughtful breaking changes
+
+### Date-Based Versions
+
+Some APIs use dates for versions:
+```
+/2024-01-01/users
+/2024-06-15/users
+```
+
+**Used by:** Stripe, GitHub API
+
+**Advantages:**
+- Clear when version was released
+- Easy to understand timeline
+- No confusion about major/minor
+
+**Disadvantages:**
+- Less intuitive for clients
+- Harder to understand what changed
+
+## Version Lifecycle
+
+### 1. Introduction Phase
+
+New version is released alongside existing version:
+```
+/v1/users  # Still supported
+/v2/users  # New version available
+```
+
+Announce new version:
+- Blog post explaining changes
+- Migration guide
+- Breaking changes list
+- Timeline for v1 deprecation
+
+### 2. Deprecation Phase
+
+Mark old version as deprecated but keep it running:
+
+```http
+GET /v1/users/123
+
+Response:
+Deprecation: true
+Sunset: Wed, 15 Jan 2025 00:00:00 GMT
+Link: </v2/users/123>; rel="successor-version"
+
+{
+  "id": 123,
+  "name": "John Doe"
+}
+```
+
+**Deprecation Headers:**
+- `Deprecation: true` - Indicates version is deprecated
+- `Sunset: <date>` - When version will be removed (RFC 8594)
+- `Link: <url>; rel="successor-version"` - Points to new version
+
+### 3. Sunset Phase
+
+Old version is shut down on announced date.
+
+Return 410 Gone for deprecated endpoints:
+```http
+GET /v1/users/123
+
+Response: 410 Gone
+{
+  "error": {
+    "code": "VERSION_SUNSET",
+    "message": "API v1 was sunset on 2025-01-15. Please use v2.",
+    "documentation_url": "https://api.example.com/docs/migration-v1-to-v2"
+  }
+}
+```
+
+## Deprecation Policy
+
+### Recommended Timeline
+
+1. **Announce deprecation** - At least 6 months before sunset
+2. **Support period** - Run both versions for 6-12 months
+3. **Sunset date** - Clear date communicated in advance
+4. **Grace period** - 30 days of 410 Gone responses before complete shutdown
+
+### Communication Channels
+
+- API response headers
+- Email to registered developers
+- Blog posts and changelog
+- Dashboard notifications
+- Documentation updates
+- Status page announcements
+
+## Migration Strategy
+
+### Provide Migration Guide
+
+```markdown
+# Migrating from v1 to v2
+
+## Breaking Changes
+
+### User Resource Changes
+
+**v1:**
+```json
+{
+  "id": 123,
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+```
+
+**v2:**
+```json
+{
+  "id": 123,
+  "first_name": "John",
+  "last_name": "Doe",
+  "email": "john@example.com"
+}
+```
+
+**Migration:**
+- Split `name` field into `first_name` and `last_name`
+- Update client code to use new fields
+```
+
+### Offer Tools
+
+- Migration scripts
+- SDK updates
+- API diff viewer
+- Compatibility layer (temporary)
+
+## Version Discovery
+
+### Root Endpoint
+
+```http
+GET /
+
+Response:
+{
+  "versions": {
+    "v1": {
+      "status": "deprecated",
+      "sunset_date": "2025-01-15",
+      "documentation_url": "https://api.example.com/docs/v1"
+    },
+    "v2": {
+      "status": "current",
+      "documentation_url": "https://api.example.com/docs/v2"
+    },
+    "v3": {
+      "status": "beta",
+      "documentation_url": "https://api.example.com/docs/v3"
+    }
+  }
+}
+```
+
+### Version Info Endpoint
+
+```http
+GET /v2/version
+
+Response:
+{
+  "version": "v2",
+  "released": "2024-01-15",
+  "status": "stable",
+  "sunset_date": null
+}
+```
+
+## OpenAPI Versioning
+
+### Separate Specs per Version
+
+```
+openapi-v1.yaml
+openapi-v2.yaml
+openapi-v3.yaml
+```
+
+Each spec is complete and independent.
+
+### Single Spec with Servers
+
+```yaml
+openapi: 3.1.0
+info:
+  title: My API
+  version: 2.0.0
+servers:
+  - url: https://api.example.com/v1
+    description: Version 1 (deprecated)
+  - url: https://api.example.com/v2
+    description: Version 2 (current)
+```
+
+## Best Practices
+
+1. **Version from day one** - Start with /v1, not /api
+2. **Major versions only** - Use v1, v2, v3 (not v1.1, v1.2)
+3. **Long deprecation periods** - Give clients time to migrate (6-12 months)
+4. **Clear communication** - Use headers, docs, emails
+5. **Maintain old versions** - Support at least 2 versions simultaneously
+6. **Document changes** - Provide detailed migration guides
+7. **Use semantic versioning** - For internal/SDK versioning
+8. **Never break without warning** - Always announce breaking changes
+9. **Provide tools** - Migration scripts, updated SDKs
+10. **Monitor usage** - Track which versions are being used
+
+## Anti-Patterns
+
+Avoid these mistakes:
+
+- **Breaking changes without version bump** - Breaks existing clients
+- **Too many versions** - Maintenance nightmare (max 2-3 active versions)
+- **Short deprecation periods** - Frustrates developers
+- **No migration path** - Makes upgrades painful
+- **Surprise sunsets** - Breaks production apps without warning
+- **Inconsistent versioning** - Different strategies for different endpoints
+- **Versioning individual endpoints** - Use consistent version across API