Integration Skill

Design robust, well-documented integration points between components and services.

Purpose

Define communication contracts:

• API design (REST, GraphQL, gRPC)
• Event schema definition
• Integration pattern selection
• Error handling and resilience

Process

1. Identify Integration Points

Map communication:

• Component-to-component
• Service-to-service
• Client-to-server
• External integrations
• Event flows

2. Choose Pattern

Select approach:

• Request/Response - Sync, immediate result
• Publish/Subscribe - Async, one-to-many
• Event Sourcing - Audit trail, replay
• API Gateway - Unified entry point

3. Design Contracts

Define specifications:

• OpenAPI for REST
• GraphQL schemas
• Protocol Buffers for gRPC
• Event schemas (JSON Schema)

4. Plan Resilience

Handle failures:

• Retry strategies
• Circuit breakers
• Timeouts
• Fallback behaviors

Output

Creates in phases/design/:

design/
├── integration/
│   ├── overview.md
│   ├── api-specs/
│   │   ├── openapi.yaml
│   │   └── events.json
│   └── patterns.md

Integration Patterns

REST API

Resource-oriented, stateless, HTTP verbs.
See REST API Fundamentals and Responses & Security.

GraphQL

Flexible queries, strong typing.
See GraphQL guides in refs/ (graphql-graphql-basics.md, graphql-schema-design-patterns.md).

gRPC

High performance, service-to-service.
See gRPC guides in refs/ (grpc-grpc-overview.md, grpc-implementation-examples.md).

Event-Driven

Async messaging, pub/sub.
See event schema guides in refs/ (event-schemas-event-structure.md, event-schemas-best-practices.md).

Error Handling

Standard HTTP status codes:

• 2xx: Success (200 OK, 201 Created, 204 No Content)
• 4xx: Client errors (400, 401, 404, 409)
• 5xx: Server errors (500, 503)

See error handling guides in refs/ (error-handling-error-response-format.md, error-handling-best-practices.md).

Resilience Patterns

• Circuit Breaker - Prevent cascading failures
• Retry with Backoff - Exponential retry delays
• Timeouts - Fail fast on slow responses
• Fallbacks - Graceful degradation

See resilience guides in refs/ (resilience-circuit-breaker-pattern.md, resilience-best-practices.md).

Versioning

Common strategies:

• URL versioning: /api/v1/resources
• Header versioning: Accept: application/vnd.api+json; version=1

See versioning guides in refs/ (versioning-versioning-strategies.md, versioning-migration-strategies.md).

Integration

With System Design

Takes component boundaries and defines:

• Interfaces between components
• Data contracts
• Communication patterns

With Data Architecture

Coordinates on:

• API data models
• Event payloads
• Serialization formats

Events

• [arch:contract:defined:success] - API contract created
• [arch:api:validated:success] - API spec validated
• [arch:event:schema:defined:success] - Event schema documented

Tips

1. API-First Design - Design before implementation
2. Version from Start - Plan for evolution
3. Document Well - Specs are executable docs
4. Error Handling - Comprehensive error responses
5. Idempotency - Make operations repeatable safely
6. Security - Auth/authz from the beginning

Reference Materials

• REST API:
  • Fundamentals
  • Responses & Security
• GraphQL:
  • Basics
  • Query Examples
  • Schema Design
  • Error Handling
  • Best Practices
• gRPC:
  • Overview
  • Implementation
  • Metadata & Headers
  • Testing
• Event Schemas:
  • Event Structure
  • Naming Conventions
  • Best Practices
• Error Handling:
  • Response Format
  • Error Classes (TS)
  • Retry Strategies
  • Best Practices
• Resilience:
  • Circuit Breaker
  • Timeout & Bulkhead
  • Rate Limiting
  • Best Practices
• Versioning:
  • Strategies
  • Migration
  • Breaking Changes
• OpenAPI Template