dojo.md 0.1.0 → 0.2.0

package/courses/api-error-handling/scenarios/level-2/circuit-breaker-pattern.yaml

@@ -0,0 +1,189 @@
+name: "Circuit Breaker Pattern for Resilience"
+level: 2
+difficulty: intermediate
+description: "Implement circuit breaker pattern to prevent cascading failures and graceful degradation"
+
+context: |
+  Your API depends on an external payment provider. Implement a circuit breaker that
+  monitors failures. When failure rate exceeds threshold, trip the circuit to stop
+  requests for a cool-down period, preventing cascading failures.
+
+scenario:
+  state:
+    circuit_breaker:
+      state: "CLOSED"
+      failure_count: 0
+      success_count: 0
+      failure_threshold: 5
+      success_threshold: 2
+      timeout_seconds: 30
+    payment_provider:
+      healthy: true
+      failure_rate: 0
+
+  endpoint: "POST /api/v1/charges"
+
+  test_cases:
+    - name: "circuit_closed_request_succeeds"
+      request:
+        body:
+          amount: 100
+          card_token: "tok_visa"
+      circuit_state: "CLOSED"
+      provider_status: "healthy"
+      expected_status: 200
+      expected_response:
+        charge_id: "charge_001"
+        status: "succeeded"
+
+    - name: "circuit_closed_provider_fails_once"
+      request:
+        body:
+          amount: 100
+          card_token: "tok_visa"
+      circuit_state: "CLOSED"
+      provider_status: "failing"
+      expected_status: 502
+      expected_response:
+        error:
+          code: "PAYMENT_PROVIDER_ERROR"
+
+    - name: "circuit_accumulates_failures"
+      request:
+        body:
+          amount: 100
+          card_token: "tok_visa"
+      circuit_state: "CLOSED"
+      provider_status: "failing"
+      consecutive_failures: 5
+      expected_status: 502
+      circuit_state_after: "OPEN"
+
+    - name: "circuit_open_request_fails_immediately"
+      request:
+        body:
+          amount: 100
+          card_token: "tok_visa"
+      circuit_state: "OPEN"
+      expected_status: 503
+      expected_response:
+        error:
+          code: "SERVICE_UNAVAILABLE"
+          message: "Payment service temporarily unavailable. Please retry later."
+      response_time_ms: "< 10"
+
+    - name: "circuit_returns_fallback_response"
+      request:
+        body:
+          amount: 100
+          card_token: "tok_visa"
+      circuit_state: "OPEN"
+      fallback_enabled: true
+      expected_status: 202
+      expected_response:
+        charge_id: "charge_002"
+        status: "pending"
+        message: "Charge queued for processing when service recovers"
+
+    - name: "circuit_half_open_test_request"
+      request:
+        body:
+          amount: 100
+          card_token: "tok_visa"
+      circuit_state: "HALF_OPEN"
+      provider_status: "healthy"
+      expected_status: 200
+      expected_response:
+        charge_id: "charge_003"
+        status: "succeeded"
+      circuit_state_after: "CLOSED"
+
+    - name: "circuit_half_open_test_fails_reopens"
+      request:
+        body:
+          amount: 100
+          card_token: "tok_visa"
+      circuit_state: "HALF_OPEN"
+      provider_status: "failing"
+      expected_status: 502
+      circuit_state_after: "OPEN"
+
+    - name: "circuit_timeout_moves_to_half_open"
+      circuit_state: "OPEN"
+      timeout_elapsed: 30
+      current_request: false
+      circuit_state_after: "HALF_OPEN"
+
+assertions:
+  - type: "api_called"
+    description: "Circuit breaker monitors failure rate"
+    test: "failure_count increments on provider errors"
+
+  - type: "outcome"
+    description: "Circuit trips when threshold exceeded"
+    test: "circuit_accumulates_failures transitions to OPEN state"
+
+  - type: "api_called"
+    description: "Open circuit fails immediately without trying provider"
+    test: "circuit_open_request_fails_immediately responds quickly"
+
+  - type: "api_called"
+    description: "Fallback behavior when circuit open"
+    test: "circuit_returns_fallback_response provides degraded service"
+
+  - type: "api_called"
+    description: "Circuit half-open allows test request"
+    test: "circuit_half_open_test_request sent to provider"
+
+  - type: "outcome"
+    description: "Successful test request closes circuit"
+    test: "circuit_half_open_test_fails_reopens transitions correctly"
+
+learning_objectives:
+  - "Understand circuit breaker states: CLOSED, OPEN, HALF_OPEN"
+  - "Monitor failures to detect persistent provider issues"
+  - "Trip circuit to prevent cascading failures"
+  - "Implement cool-down period for recovery"
+  - "Test recovery with half-open state"
+  - "Return appropriate status codes for circuit states"
+  - "Implement fallback strategies for open circuits"
+
+circuit_breaker_states:
+  "CLOSED": "Normal operation, requests flow to provider"
+  "OPEN": "Too many failures, requests fail immediately, no provider calls"
+  "HALF_OPEN": "Cool-down period elapsed, allow test request to check if provider recovered"
+
+state_transitions:
+  "CLOSED → OPEN": "When failure_count exceeds threshold"
+  "OPEN → HALF_OPEN": "When timeout_seconds elapsed"
+  "HALF_OPEN → CLOSED": "When test request succeeds"
+  "HALF_OPEN → OPEN": "When test request fails"
+
+implementation_considerations:
+  "failure_detection": "Monitor 5xx errors and timeouts"
+  "failure_threshold": "Typically 5-10 consecutive failures"
+  "cool_down_period": "30-60 seconds typical"
+  "half_open_testing": "Allow single request through to test recovery"
+  "fallback_strategy": "Queue requests, return degraded response, or fail fast"
+  "metrics": "Track state transitions, time in each state"
+
+fallback_strategies:
+  "fast_fail": "Return 503 Service Unavailable immediately"
+  "queue_requests": "Enqueue for async processing when provider recovers"
+  "degraded_mode": "Use cached data or return partial results"
+  "alternate_provider": "Failover to backup provider"
+
+common_mistakes:
+  - "Not implementing circuit breaker for external dependencies"
+  - "Allowing too many failures before tripping circuit"
+  - "Cool-down period too short (allows rapid retries)"
+  - "Not monitoring time spent in OPEN state"
+  - "Failing to test recovery in HALF_OPEN state"
+  - "Not logging circuit state changes"
+  - "Returning ambiguous status codes (500 vs 503)"
+
+libraries:
+  "hystrix": "Netflix Hystrix - Java circuit breaker library"
+  "polly": ".NET resilience and transient-fault-handling library"
+  "opossum": "Node.js circuit breaker"
+  "pybreaker": "Python implementation"

package/courses/api-error-handling/scenarios/level-2/idempotency-retry-logic.yaml

@@ -0,0 +1,159 @@
+name: "Idempotency and Retry Logic"
+level: 2
+difficulty: intermediate
+description: "Implement idempotent operations and safe retry strategies to prevent duplicate processing"
+
+context: |
+  Design payment processing APIs that are idempotent. Clients send a unique idempotency
+  key with each request. If a retry arrives with the same key, return the same result
+  without processing again. This prevents double-charging when networks fail.
+
+scenario:
+  state:
+    payments:
+      "pay_001": { customer_id: "cust_1", amount: 100, status: "completed" }
+    customers:
+      "cust_1": { balance: 1000 }
+      "cust_2": { balance: 500 }
+    idempotency_keys:
+      "idem_key_123": { payment_id: "pay_001", status: "completed", created_at: "2024-01-01T10:00:00Z" }
+
+  endpoint: "POST /api/v1/payments"
+
+  test_cases:
+    - name: "initial_payment_request"
+      request:
+        body:
+          customer_id: "cust_2"
+          amount: 50
+        headers:
+          Idempotency-Key: "idem_key_456"
+      expected_status: 201
+      expected_response:
+        payment_id: "pay_002"
+        customer_id: "cust_2"
+        amount: 50
+        status: "completed"
+
+    - name: "retry_same_idempotency_key_returns_same_result"
+      request:
+        body:
+          customer_id: "cust_2"
+          amount: 50
+        headers:
+          Idempotency-Key: "idem_key_456"
+      expected_status: 201
+      expected_response:
+        payment_id: "pay_002"
+        customer_id: "cust_2"
+        amount: 50
+        status: "completed"
+
+    - name: "duplicate_charge_prevented"
+      request:
+        body:
+          customer_id: "cust_2"
+          amount: 50
+        headers:
+          Idempotency-Key: "idem_key_456"
+      expected_effect: "customer balance unchanged (only charged once)"
+
+    - name: "different_key_different_charge"
+      request:
+        body:
+          customer_id: "cust_2"
+          amount: 50
+        headers:
+          Idempotency-Key: "idem_key_789"
+      expected_status: 201
+      expected_response:
+        payment_id: "pay_003"
+
+    - name: "missing_idempotency_key_warning"
+      request:
+        body:
+          customer_id: "cust_2"
+          amount: 50
+      expected_status: 201
+      expected_response:
+        warning: "Idempotency-Key not provided. Retries may result in duplicate charges."
+
+    - name: "request_in_progress"
+      request:
+        body:
+          customer_id: "cust_2"
+          amount: 50
+        headers:
+          Idempotency-Key: "idem_key_processing"
+        concurrent_request: true
+      expected_status: 409
+      expected_response:
+        error:
+          code: "REQUEST_IN_PROGRESS"
+          message: "Request with this Idempotency-Key is currently being processed"
+
+assertions:
+  - type: "api_called"
+    description: "Idempotency-Key header required for non-idempotent operations"
+    test: "POST /payments accepts Idempotency-Key header"
+
+  - type: "api_called"
+    description: "Same idempotency key returns same result"
+    test: "retry_same_idempotency_key_returns_same_result succeeds"
+
+  - type: "outcome"
+    description: "Duplicate processing prevented"
+    test: "duplicate_charge_prevented prevents second charge"
+
+  - type: "api_called"
+    description: "Different keys processed as different requests"
+    test: "different_key_different_charge creates separate payment"
+
+  - type: "api_called"
+    description: "Concurrent requests with same key handled"
+    test: "request_in_progress returns 409 for concurrent calls"
+
+learning_objectives:
+  - "Understand idempotency and why it's critical for financial operations"
+  - "Implement idempotency key tracking and storage"
+  - "Return consistent results for duplicate idempotent requests"
+  - "Prevent double-processing with idempotent operations"
+  - "Handle request-in-progress scenarios"
+  - "Design safe retry strategies with exponential backoff"
+  - "Distinguish between idempotent and non-idempotent operations"
+
+idempotency_implementation:
+  "storage": "Idempotency keys stored with request ID, status, and result"
+  "cache_ttl": "Keep entries for 24 hours minimum for safety"
+  "duplicate_detection": "Check key before processing, return stored result if found"
+  "status_tracking": "Track PENDING, COMPLETED, FAILED states"
+
+retry_strategy:
+  "idempotent_operations": "GET, PUT, DELETE - safe to retry with backoff"
+  "non_idempotent_operations": "POST typically requires idempotency key"
+  "backoff_pattern": "exponential: 1s, 2s, 4s, 8s, 16s"
+  "max_retries": "Typically 5-10 depending on SLA"
+
+headers:
+  "Idempotency-Key": "Unique identifier for the logical operation (required for POST/PATCH)"
+  "Idempotency-Replay": "Boolean indicating if this is a replay of previous request"
+
+common_mistakes:
+  - "Not implementing idempotency for payment operations"
+  - "Charging twice due to missing idempotency checks"
+  - "Not persisting idempotency keys long enough"
+  - "Retrying non-idempotent operations blindly"
+  - "Not informing clients of idempotency requirements"
+  - "Failing to handle requests in progress"
+
+example_idempotent_operations: |
+  POST /api/v1/payments (with Idempotency-Key header)
+  POST /api/v1/orders (with Idempotency-Key header)
+  POST /api/v1/subscriptions (with Idempotency-Key header)
+
+  These modify state and must be idempotent to prevent duplicates.
+
+  Safe to retry without idempotency key:
+  GET /api/v1/users (read-only)
+  DELETE /api/v1/users/{id} (idempotent - deleting twice = same result)
+  PUT /api/v1/users/{id} (idempotent - updating twice with same data = same result)

package/courses/api-error-handling/scenarios/level-2/rfc-7807-problem-details.yaml

@@ -0,0 +1,178 @@
+name: "RFC 7807 Problem Details Standard"
+level: 2
+difficulty: intermediate
+description: "Implement standardized error responses using RFC 7807 Problem Details format"
+
+context: |
+  Migrate your API error responses to the RFC 7807 standard. This standardized format
+  improves interoperability across tools and clients. Implement problem details with
+  type URI, title, status, detail, and instance fields.
+
+scenario:
+  state:
+    bank_accounts:
+      "acc_001": { balance: 5000, account_holder: "John Doe" }
+      "acc_002": { balance: 100, account_holder: "Jane Smith" }
+
+  endpoint: "POST /api/v1/accounts/{accountId}/transfer"
+
+  test_cases:
+    - name: "successful_transfer"
+      request:
+        path: "/api/v1/accounts/acc_001/transfer"
+        body:
+          to_account: "acc_002"
+          amount: 100
+      expected_status: 200
+      expected_response:
+        transaction_id: "txn_123"
+        status: "completed"
+
+    - name: "insufficient_funds_rfc7807"
+      request:
+        path: "/api/v1/accounts/acc_002/transfer"
+        body:
+          to_account: "acc_001"
+          amount: 500
+      expected_status: 422
+      expected_response:
+        type: "https://api.example.com/errors/insufficient-funds"
+        title: "Insufficient Funds"
+        status: 422
+        detail: "Account acc_002 has balance of 100 but requires 500 for this transfer"
+        instance: "/api/v1/accounts/acc_002/transfer"
+        balance: 100
+        required_amount: 500
+
+    - name: "account_not_found_rfc7807"
+      request:
+        path: "/api/v1/accounts/acc_999/transfer"
+        body:
+          to_account: "acc_001"
+          amount: 100
+      expected_status: 404
+      expected_response:
+        type: "https://api.example.com/errors/account-not-found"
+        title: "Account Not Found"
+        status: 404
+        detail: "The account acc_999 does not exist in the system"
+        instance: "/api/v1/accounts/acc_999/transfer"
+
+    - name: "invalid_amount_validation"
+      request:
+        path: "/api/v1/accounts/acc_001/transfer"
+        body:
+          to_account: "acc_002"
+          amount: -50
+      expected_status: 400
+      expected_response:
+        type: "https://api.example.com/errors/validation-error"
+        title: "Validation Error"
+        status: 400
+        detail: "The request body contains invalid values"
+        instance: "/api/v1/accounts/acc_001/transfer"
+        validation_errors:
+          - field: "amount"
+            message: "Amount must be positive"
+            rejected_value: -50
+
+    - name: "self_transfer_error"
+      request:
+        path: "/api/v1/accounts/acc_001/transfer"
+        body:
+          to_account: "acc_001"
+          amount: 100
+      expected_status: 409
+      expected_response:
+        type: "https://api.example.com/errors/invalid-operation"
+        title: "Invalid Operation"
+        status: 409
+        detail: "Cannot transfer funds to the same account"
+        instance: "/api/v1/accounts/acc_001/transfer"
+
+assertions:
+  - type: "api_called"
+    description: "type field contains URI identifying problem"
+    test: "error response includes type field with URI"
+
+  - type: "api_called"
+    description: "title field is human-readable problem type"
+    test: "title field is constant for same error type"
+
+  - type: "api_called"
+    description: "status field echoes HTTP status code"
+    test: "status field matches HTTP response status"
+
+  - type: "api_called"
+    description: "detail field explains specific instance"
+    test: "detail contains instance-specific information"
+
+  - type: "api_called"
+    description: "instance field identifies affected resource"
+    test: "instance field contains request path"
+
+  - type: "api_called"
+    description: "Extensions included for domain-specific details"
+    test: "error response includes custom fields as extensions"
+
+  - type: "outcome"
+    description: "RFC 7807 enables standard error tooling"
+    test: "error responses conform to standard specification"
+
+learning_objectives:
+  - "Understand RFC 7807 Problem Details specification"
+  - "Map problem types to type URIs"
+  - "Distinguish between title (constant) and detail (instance-specific)"
+  - "Include appropriate HTTP status codes in problem details"
+  - "Extend RFC 7807 with domain-specific fields"
+  - "Communicate problem details to generic HTTP clients"
+
+rfc7807_fields:
+  "type": "URI identifying problem type (required, should dereference to documentation)"
+  "title": "Short human-readable summary of problem type (required, same for same type)"
+  "status": "HTTP status code (optional, but recommended)"
+  "detail": "Human-readable explanation of specific problem instance (optional, instance-specific)"
+  "instance": "URI identifying specific problem occurrence (optional, usually request path)"
+
+example_error_responses: |
+  Example 1: Insufficient Funds
+  {
+    "type": "https://api.example.com/errors/insufficient-funds",
+    "title": "Insufficient Funds",
+    "status": 422,
+    "detail": "Account acc_002 has balance of 100 but requires 500 for this transfer",
+    "instance": "/api/v1/accounts/acc_002/transfer",
+    "balance": 100,
+    "required_amount": 500
+  }
+
+  Example 2: Validation Error
+  {
+    "type": "https://api.example.com/errors/validation-error",
+    "title": "Validation Error",
+    "status": 400,
+    "detail": "The request body contains invalid values",
+    "instance": "/api/v1/accounts/acc_001/transfer",
+    "validation_errors": [
+      {
+        "field": "amount",
+        "message": "Amount must be positive",
+        "rejected_value": -50
+      }
+    ]
+  }
+
+advantages:
+  - "Standard format recognized by HTTP tools and libraries"
+  - "Generic clients can handle errors without API-specific code"
+  - "Clear semantics: type vs title vs detail"
+  - "Extensibility through custom fields"
+  - "Easier debugging and error tracking"
+  - "Better integration with API gateways and monitoring"
+
+content_type:
+  "application/problem+json": "Standard MIME type for RFC 7807 responses"
+
+references:
+  - "https://datatracker.ietf.org/doc/html/rfc7807"
+  - "https://datatracker.ietf.org/doc/html/rfc9457 (RFC 9457 - Problem Details for HTTP APIs)"