Integration Specification Writer

Expert in writing comprehensive integration specifications that serve as contracts between systems.

Essential Components

Every integration spec must include:

• Integration Overview: Purpose, scope, and high-level architecture

• Authentication & Authorization: Security mechanisms and token handling

• Endpoint Definitions: Complete API contract with request/response schemas

• Data Models: Structured definitions of all data objects

• Error Handling: Comprehensive error codes and recovery procedures

• Rate Limiting: Throttling rules and quota management

• Sequence Diagrams: Visual representation of interaction flows

• Testing Scenarios: Integration test cases and validation criteria

Integration Specification Template

Integration Specification: [System A] ↔ [System B]

Version: 1.0.0 Last Updated: [Date] Authors: [Names] Status: [Draft/Review/Approved/Production]

1. Overview

1.1 Purpose

[Brief description of why this integration exists]

1.2 Scope

• In Scope: [What this integration covers]
• Out of Scope: [What this integration does not cover]

1.3 Architecture Diagram

[Include diagram showing systems, data flow, and key components]

2. Authentication & Authorization

2.1 Authentication Method

[OAuth 2.0 / API Key / JWT / mTLS]

2.2 Credential Management

[How credentials are obtained, stored, and rotated]

3. Endpoints

[Detailed endpoint specifications]

4. Data Models

[Complete schema definitions]

5. Error Handling

[Error codes and recovery procedures]

6. Rate Limiting

[Throttling rules and quotas]

7. Testing

[Test scenarios and validation criteria]

Authentication Specification

authentication: type: "Bearer Token (OAuth 2.0)" flow: "Client Credentials"

endpoints: token: url: "https://api.example.com/oauth/token" method: "POST" content_type: "application/x-www-form-urlencoded"

request: grant_type: "client_credentials" client_id: "{CLIENT_ID}" client_secret: "{CLIENT_SECRET}" scope: "read write"

response: access_token: "string" token_type: "Bearer" expires_in: 3600 scope: "read write"

usage: header: "Authorization: Bearer {access_token}" content_type: "application/json"

token_refresh: automatic: true threshold_seconds: 300 # Refresh 5 min before expiry retry_attempts: 3 retry_delay_seconds: 5

security_requirements: - "Store credentials in secure vault (not in code)" - "Use HTTPS for all requests" - "Implement token caching to reduce auth calls" - "Log authentication failures for monitoring"

Endpoint Documentation Standards

POST /api/v1/orders

endpoint: method: "POST" path: "/api/v1/orders" description: "Create a new order in the system"

headers: required: Authorization: "Bearer {access_token}" Content-Type: "application/json" X-Request-ID: "string (UUID) - for request tracing" optional: X-Idempotency-Key: "string - prevents duplicate processing"

request: body: type: "object" required: ["customer_id", "items"] properties: customer_id: type: "string" description: "Unique customer identifier" constraints: "max 50 characters, alphanumeric" example: "CUST-12345" items: type: "array" minItems: 1 maxItems: 100 items: type: "object" required: ["product_id", "quantity"] properties: product_id: type: "string" description: "Product SKU" example: "SKU-001" quantity: type: "integer" minimum: 1 maximum: 999 example: 2 unit_price: type: "number" format: "decimal" description: "Price per unit (2 decimal places)" example: 29.99 shipping_address: type: "object" required: ["street", "city", "postal_code", "country"] properties: street: type: "string" maxLength: 100 city: type: "string" maxLength: 50 postal_code: type: "string" pattern: "^\d{5}(-\d{4})?$" country: type: "string" format: "ISO 3166-1 alpha-2"

responses: 201: description: "Order created successfully" body: order_id: "ORD-12345678" status: "pending" total_amount: 299.99 currency: "USD" created_at: "2024-01-15T10:30:00Z" estimated_delivery: "2024-01-20T10:00:00Z" tracking_url: "https://api.example.com/orders/ORD-12345678/track"

400: description: "Invalid request" body: error_code: "VALIDATION_ERROR" message: "Request validation failed" details: - field: "items[0].quantity" error: "Must be between 1 and 999"

401: description: "Authentication failed" body: error_code: "UNAUTHORIZED" message: "Invalid or expired access token"

409: description: "Conflict" body: error_code: "DUPLICATE_ORDER" message: "Order with this idempotency key already exists" existing_order_id: "ORD-12345678"

429: description: "Rate limit exceeded" headers: Retry-After: "60" X-RateLimit-Limit: "100" X-RateLimit-Remaining: "0" X-RateLimit-Reset: "1704067200"

Error Handling Specification

error_format: standard_response: error_code: "string - machine-readable error code" message: "string - human-readable description" details: "array - specific field errors (optional)" request_id: "string - for support reference" timestamp: "string - ISO 8601 datetime"

error_codes: VALIDATION_ERROR: http_status: 400 description: "Request body failed validation" retry_strategy: "Do not retry - fix request and resubmit" resolution: "Check error details for specific field issues"

INVALID_CUSTOMER: http_status: 400 description: "Customer ID not found or inactive" retry_strategy: "Do not retry - verify customer data" resolution: "Validate customer exists and has active status"

UNAUTHORIZED: http_status: 401 description: "Invalid or expired authentication" retry_strategy: "Refresh token and retry once" resolution: "Obtain new access token"

FORBIDDEN: http_status: 403 description: "Insufficient permissions" retry_strategy: "Do not retry" resolution: "Contact admin to verify API scopes"

NOT_FOUND: http_status: 404 description: "Requested resource does not exist" retry_strategy: "Do not retry" resolution: "Verify resource ID is correct"

CONFLICT: http_status: 409 description: "Resource state conflict" retry_strategy: "Fetch current state and reconcile" resolution: "Check existing resource and merge changes"

RATE_LIMIT_EXCEEDED: http_status: 429 description: "Too many requests" retry_strategy: "Wait for Retry-After header duration" resolution: "Implement exponential backoff" headers: Retry-After: "Seconds to wait before retry" X-RateLimit-Reset: "Unix timestamp when limit resets"

INTERNAL_ERROR: http_status: 500 description: "Unexpected server error" retry_strategy: "Retry with exponential backoff (max 3 attempts)" resolution: "If persists, contact support with request_id"

SERVICE_UNAVAILABLE: http_status: 503 description: "Service temporarily unavailable" retry_strategy: "Retry with exponential backoff" resolution: "Check status page, retry after delay"

Webhook Specification

webhooks: overview: description: "Real-time event notifications via HTTP POST" delivery: "At-least-once delivery guarantee" format: "JSON payload with HMAC signature"

configuration: endpoint_url: "Your HTTPS endpoint" secret_key: "Shared secret for signature verification" events: ["order.created", "order.updated", "order.cancelled"]

security: signature_header: "X-Webhook-Signature" signature_algorithm: "HMAC-SHA256" timestamp_header: "X-Webhook-Timestamp" replay_prevention: "Reject if timestamp > 5 minutes old"

verification_example: python: | import hmac import hashlib

  def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
      expected = hmac.new(
          secret.encode(),
          payload,
          hashlib.sha256
      ).hexdigest()
      return hmac.compare_digest(f"sha256={expected}", signature)

payload_structure: event_id: "string - unique event identifier" event_type: "string - e.g., order.created" timestamp: "string - ISO 8601" data: object_type: "string - e.g., order" object_id: "string - resource identifier" changes: "object - changed fields (for update events)"

retry_policy: attempts: 5 schedule: - "Immediate" - "1 minute" - "5 minutes" - "30 minutes" - "2 hours" success_criteria: "HTTP 2xx response within 30 seconds" failure_action: "Event logged, alert sent, manual retry available"

expected_response: status: "2xx within 30 seconds" body: "Optional - ignored"

events: order.created: description: "Fired when a new order is created" payload: order_id: "string" customer_id: "string" total_amount: "number" items: "array" created_at: "string"

order.updated:
  description: "Fired when order status changes"
  payload:
    order_id: "string"
    previous_status: "string"
    current_status: "string"
    updated_at: "string"

Rate Limiting Specification

rate_limits: default: requests_per_minute: 100 requests_per_day: 10000 burst_allowance: "150% for up to 30 seconds"

per_endpoint: "/api/v1/orders": method: "POST" limit: "100 requests/minute" reason: "Write operation - higher resource cost"

"/api/v1/orders":
  method: "GET"
  limit: "300 requests/minute"
  reason: "Read operation - cached responses"

"/api/v1/search":
  limit: "60 requests/minute"
  reason: "Expensive search operation"

headers: X-RateLimit-Limit: "Requests allowed per window" X-RateLimit-Remaining: "Requests remaining" X-RateLimit-Reset: "Unix timestamp when window resets"

exceeded_response: status: 429 body: error_code: "RATE_LIMIT_EXCEEDED" message: "Rate limit exceeded" retry_after: 60

best_practices: - "Implement client-side rate limiting" - "Use exponential backoff on 429 responses" - "Cache responses where possible" - "Batch operations when available"

Sequence Diagram Example

sequenceDiagram participant Client participant API Gateway participant Order Service participant Payment Service participant Inventory Service participant Notification Service

Client->>API Gateway: POST /api/v1/orders
API Gateway->>API Gateway: Validate Token
API Gateway->>Order Service: Create Order

Order Service->>Inventory Service: Reserve Items
Inventory Service-->>Order Service: Reservation Confirmed

Order Service->>Payment Service: Process Payment
Payment Service-->>Order Service: Payment Success

Order Service->>Order Service: Update Order Status
Order Service-->>API Gateway: Order Created (201)
API Gateway-->>Client: Order Response

Order Service--)Notification Service: order.created Event
Notification Service--)Client: Webhook: order.created

Testing Scenarios

test_scenarios: happy_path: name: "Successful order creation" preconditions: - "Valid customer account exists" - "Products are in stock" - "Payment method is valid" request: method: "POST" path: "/api/v1/orders" body: "{valid order payload}" expected: status: 201 response_contains: ["order_id", "status", "total_amount"] postconditions: - "Order record created in database" - "Inventory reserved" - "Payment processed" - "Webhook sent"

validation_errors: - name: "Missing required field" request: "{order without customer_id}" expected_status: 400 expected_error: "VALIDATION_ERROR"

- name: "Invalid quantity"
  request: "{order with quantity: 0}"
  expected_status: 400
  expected_error: "VALIDATION_ERROR"

edge_cases: - name: "Insufficient inventory" setup: "Set product stock to 0" expected_status: 409 expected_error: "INSUFFICIENT_INVENTORY"

- name: "Payment failure"
  setup: "Configure payment service to decline"
  expected_status: 402
  expected_error: "PAYMENT_FAILED"
  postcondition: "Inventory reservation released"

idempotency: name: "Duplicate request handling" steps: - "Send order with X-Idempotency-Key: abc123" - "Response: 201 Created, order_id: ORD-001" - "Send same request with same idempotency key" - "Response: 200 OK, order_id: ORD-001 (same order)"

Environment Configuration

environments: sandbox: base_url: "https://api-sandbox.example.com" purpose: "Development and testing" rate_limits: "10x production limits" data: "Test data, reset daily at 00:00 UTC" credentials: "Separate sandbox API keys"

staging: base_url: "https://api-staging.example.com" purpose: "Pre-production validation" rate_limits: "Same as production" data: "Anonymized production-like data"

production: base_url: "https://api.example.com" sla: uptime: "99.9%" response_time_p95: "<200ms" response_time_p99: "<500ms" maintenance_window: "Sundays 02:00-04:00 UTC" support: "support@example.com"

Лучшие практики

• Version everything — версионирование в URL и заголовках

• Idempotency — документируйте идемпотентные операции

• Error detail — достаточно информации для отладки

• Rate limit transparency — всегда возвращайте лимиты в headers

• Webhook reliability — retry policy и signature verification

• Environment parity — sandbox максимально похож на production