aigroup-workflow 2.1.1 → 2.2.0

package/skills/api-designer/references/rest-patterns.md

@@ -1,335 +0,0 @@
-# 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/skills/api-designer/references/versioning.md

@@ -1,391 +0,0 @@
-# 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