dojo.md 0.1.0 → 0.2.1

package/courses/api-error-handling/scenarios/level-1/request-validation-errors.yaml

@@ -0,0 +1,208 @@
+name: "Request Validation Error Handling"
+level: 1
+difficulty: beginner
+description: "Handle common validation errors: missing fields, invalid types, constraint violations"
+
+context: |
+  Implement comprehensive input validation for a user registration endpoint.
+  Handle missing fields, invalid formats, constraint violations, and size limits.
+
+scenario:
+  state:
+    existing_users:
+      - email: "john@example.com"
+      - email: "jane@example.com"
+    validation_rules:
+      email: "required, valid email format, unique"
+      password: "required, minimum 8 characters"
+      name: "required, non-empty string, max 100 characters"
+      age: "optional, integer, must be 18+"
+
+  endpoint: "POST /api/v1/users/register"
+
+  test_cases:
+    - name: "valid_registration"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: "New User"
+          age: 25
+      expected_status: 201
+      expected_response:
+        user_id: "user_new_123"
+        email: "newuser@example.com"
+
+    - name: "missing_email"
+      request:
+        body:
+          password: "SecurePassword123"
+          name: "New User"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "MISSING_REQUIRED_FIELD"
+          details:
+            field: "email"
+
+    - name: "missing_password"
+      request:
+        body:
+          email: "newuser@example.com"
+          name: "New User"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "MISSING_REQUIRED_FIELD"
+          details:
+            field: "password"
+
+    - name: "invalid_email_format"
+      request:
+        body:
+          email: "not-an-email"
+          password: "SecurePassword123"
+          name: "New User"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "INVALID_EMAIL_FORMAT"
+          message: "Email must be a valid email address"
+
+    - name: "password_too_short"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "short"
+          name: "New User"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Password must be at least 8 characters"
+
+    - name: "name_exceeds_max_length"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: "A" * 101
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Name must not exceed 100 characters"
+
+    - name: "empty_name"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: ""
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Name cannot be empty"
+
+    - name: "age_below_minimum"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: "Young User"
+          age: 17
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Age must be 18 or older"
+
+    - name: "age_invalid_type"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: "User"
+          age: "twenty-five"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "INVALID_FIELD_TYPE"
+          details:
+            field: "age"
+            expected_type: "integer"
+            received_type: "string"
+
+    - name: "duplicate_email"
+      request:
+        body:
+          email: "john@example.com"
+          password: "SecurePassword123"
+          name: "John Copy"
+      expected_status: 409
+      expected_response:
+        error:
+          code: "EMAIL_ALREADY_EXISTS"
+          message: "An account with this email already exists"
+
+    - name: "multiple_validation_errors"
+      request:
+        body:
+          password: "short"
+          name: ""
+          age: 10
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Multiple validation errors"
+          details:
+            errors:
+              - field: "email"
+                code: "MISSING_REQUIRED_FIELD"
+              - field: "password"
+                code: "TOO_SHORT"
+              - field: "name"
+                code: "EMPTY"
+
+assertions:
+  - type: "http_status"
+    description: "400 Bad Request for validation errors"
+    test: "all validation errors return 400 status"
+
+  - type: "api_called"
+    description: "Missing required fields identified"
+    test: "MISSING_REQUIRED_FIELD error for absent email"
+
+  - type: "api_called"
+    description: "Invalid format errors detected"
+    test: "INVALID_EMAIL_FORMAT error for malformed email"
+
+  - type: "api_called"
+    description: "Constraint violations reported"
+    test: "Password length constraint violation returns error"
+
+  - type: "http_status"
+    description: "409 Conflict for duplicate unique fields"
+    test: "duplicate email returns 409"
+
+  - type: "api_called"
+    description: "Multiple errors reported together"
+    test: "multiple validation errors returned as array"
+
+learning_objectives:
+  - "Validate required vs optional fields"
+  - "Check data type correctness before processing"
+  - "Validate format constraints (email, URL, phone number)"
+  - "Enforce business rule constraints (min/max, uniqueness)"
+  - "Report multiple validation errors together"
+  - "Use 409 Conflict for duplicate unique constraints"
+
+common_mistakes:
+  - "Failing to validate email format before storage"
+  - "Not checking for duplicate emails/unique constraints"
+  - "Accepting invalid data types without type checking"
+  - "Returning 200 OK with validation error message"
+  - "Only reporting first error instead of all validation issues"
+  - "Not providing enough detail about what validation failed"

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)