engineering
Integration Specification
Write integration specifications — defining data flows, API contracts, authentication, error handling, retry logic, and monitoring requirements for system-to-system connections.
integrationspecificationAPIdata-flowerror-handlingcontracts
Works well with agents
Works well with skills
$ npx skills add The-AI-Directory-Company/(…) --skill integration-specificationintegration-specification/
SKILL.md
Markdown
| 1 | |
| 2 | # Integration Specification |
| 3 | |
| 4 | ## Before you start |
| 5 | |
| 6 | Gather the following from the user. Do not proceed until you have answers to at least items 1-4: |
| 7 | |
| 8 | 1. **Which two systems are being connected?** Name the source and destination. Include versions if relevant. |
| 9 | 2. **What data flows between them?** Entities, fields, direction (one-way or bidirectional), and expected volume. |
| 10 | 3. **What triggers the data flow?** Event-driven (webhook, message queue), scheduled (cron, polling), or on-demand (API call)? |
| 11 | 4. **Authentication on both sides?** API keys, OAuth, mutual TLS, service accounts — what does each system support? |
| 12 | 5. **SLA requirements?** Max acceptable latency, throughput targets, and uptime expectations. |
| 13 | 6. **What happens when one system is down?** Must data be queued, retried, or is loss acceptable? |
| 14 | |
| 15 | If the user says "integrate system A with system B" without specifics, push back: "What data needs to move, in which direction, and what triggers the transfer?" |
| 16 | |
| 17 | ## Integration specification template |
| 18 | |
| 19 | ### 1. Overview |
| 20 | |
| 21 | Write 2-3 sentences covering: |
| 22 | - The two systems being connected and their roles (producer vs. consumer) |
| 23 | - The business purpose of the integration |
| 24 | - The integration pattern: synchronous request/response, asynchronous messaging, event-driven, or batch ETL |
| 25 | |
| 26 | ### 2. Data Flow Diagram |
| 27 | |
| 28 | Define each data flow as a row: |
| 29 | |
| 30 | | Flow | Source | Destination | Trigger | Payload | Frequency | |
| 31 | |------|--------|-------------|---------|---------|-----------| |
| 32 | | Create order | Order Service | Fulfillment API | Order placed event | Order JSON | ~500/hour peak | |
| 33 | | Sync inventory | Warehouse DB | Product Service | Scheduled (every 5 min) | Inventory delta CSV | 288/day | |
| 34 | |
| 35 | Include the direction arrow in the diagram. For bidirectional flows, document each direction as a separate row. |
| 36 | |
| 37 | ### 3. API Contracts |
| 38 | |
| 39 | For each endpoint or message in the integration, specify: |
| 40 | |
| 41 | - **Method and URL** (or queue/topic name for async) |
| 42 | - **Request headers** — Content-Type, Authorization, idempotency keys |
| 43 | - **Request body** — Full schema with field names, types, required/optional, and constraints |
| 44 | - **Response body** — Success shape and error shape |
| 45 | - **Status codes** — Every expected code with its meaning in this integration's context |
| 46 | |
| 47 | Provide a concrete example request and response for each contract. Do not leave schemas abstract. |
| 48 | |
| 49 | ### 4. Authentication and Authorization |
| 50 | |
| 51 | Document for each system: |
| 52 | |
| 53 | - Auth mechanism (API key, OAuth 2.0 client credentials, mutual TLS) |
| 54 | - Token/key rotation procedure and frequency |
| 55 | - Scopes or permissions required |
| 56 | - Where credentials are stored (vault, environment variables — never hardcoded) |
| 57 | |
| 58 | ### 5. Error Handling |
| 59 | |
| 60 | Classify errors into three categories and define the response for each: |
| 61 | |
| 62 | | Category | Examples | Action | |
| 63 | |----------|----------|--------| |
| 64 | | Transient | 429, 503, timeout, connection reset | Retry with backoff | |
| 65 | | Permanent | 400, 401, 404, schema validation failure | Alert and dead-letter | |
| 66 | | Partial | Batch with some failed records | Process successes, retry failures separately | |
| 67 | |
| 68 | ### 6. Retry Logic |
| 69 | |
| 70 | Specify the exact retry policy: |
| 71 | |
| 72 | - **Strategy**: Exponential backoff with jitter |
| 73 | - **Initial delay**: e.g., 1 second |
| 74 | - **Max retries**: e.g., 5 |
| 75 | - **Max delay cap**: e.g., 60 seconds |
| 76 | - **Circuit breaker threshold**: e.g., 10 consecutive failures opens the circuit for 5 minutes |
| 77 | - **Dead-letter handling**: Where do permanently failed messages go? Who gets alerted? |
| 78 | |
| 79 | ### 7. Monitoring and Alerting |
| 80 | |
| 81 | Define what to measure and when to alert: |
| 82 | |
| 83 | | Metric | Threshold | Alert | |
| 84 | |--------|-----------|-------| |
| 85 | | End-to-end latency (P99) | > 2 seconds | Warning | |
| 86 | | Error rate | > 1% over 5 minutes | Critical | |
| 87 | | Queue depth / dead-letter size | > 10,000 / > 0 | Warning / Critical | |
| 88 | |
| 89 | ### 8. Data Mapping |
| 90 | |
| 91 | Map fields between source and target systems: |
| 92 | |
| 93 | | Source Field | Source Type | Target Field | Target Type | Transform | |
| 94 | |-------------|------------|-------------|------------|-----------| |
| 95 | | `user.email` | string | `contact_email` | varchar(255) | Lowercase, trim | |
| 96 | | `created_at` | Unix epoch (ms) | `creation_date` | ISO 8601 | Convert with UTC timezone | |
| 97 | | `status` | enum (1,2,3) | `order_status` | string | Map: 1=pending, 2=active, 3=closed | |
| 98 | |
| 99 | Document every transformation, default value, and nullable field explicitly. |
| 100 | |
| 101 | ## Quality checklist |
| 102 | |
| 103 | Before delivering the specification, verify: |
| 104 | |
| 105 | - [ ] Every data flow has a defined trigger, direction, payload, and frequency |
| 106 | - [ ] API contracts include concrete request/response examples, not just abstract schemas |
| 107 | - [ ] Authentication covers both systems with rotation procedures documented |
| 108 | - [ ] Errors are classified (transient, permanent, partial) with specific handling for each |
| 109 | - [ ] Retry policy specifies strategy, delays, max attempts, and circuit breaker thresholds |
| 110 | - [ ] Dead-letter handling is defined — failed messages are never silently dropped |
| 111 | - [ ] Monitoring covers latency, error rate, queue depth, and auth token expiry |
| 112 | - [ ] Data mapping documents every field transformation, not just the obvious ones |
| 113 | - [ ] Idempotency requirements are stated — can the consumer safely receive the same message twice? |
| 114 | |
| 115 | ## Common mistakes to avoid |
| 116 | |
| 117 | - **Assuming both systems share the same data model.** Document every field mapping and transformation, including timezone handling and enum translations. |
| 118 | - **No retry policy.** "We'll handle errors" is not a spec. Define the exact backoff strategy, max retries, and what happens after all retries are exhausted. |
| 119 | - **Ignoring partial failures in batch operations.** A batch of 100 records where 3 fail needs a clear strategy — do you reject the whole batch or process the 97 successes? |
| 120 | - **Missing idempotency.** If a webhook fires twice, will the consumer create duplicate records? Specify idempotency keys for every write operation. |
| 121 | - **Monitoring as an afterthought.** If you cannot tell whether the integration is healthy without checking logs, you do not have monitoring. |
| 122 |