| name | wicked-garden-engineering-integration |
| description | Design API contracts, service boundaries, and integration patterns.
Define how components and services communicate and interoperate.
Use when: "API design", "service integration", "how do these communicate",
"API contract", "integration pattern", "REST API", "GraphQL", "event schema"
|
| portability | portable |
| phase_relevance | ["design","build"] |
| archetype_relevance | ["*"] |
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
- API-First Design - Design before implementation
- Version from Start - Plan for evolution
- Document Well - Specs are executable docs
- Error Handling - Comprehensive error responses
- Idempotency - Make operations repeatable safely
- Security - Auth/authz from the beginning
Reference Materials
- REST API:
- GraphQL:
- gRPC:
- Event Schemas:
- Error Handling:
- Resilience:
- Versioning:
- OpenAPI Template
