Enterprise Integration Api Developer

Enterprise Integration API Developer

When to Use

• Design enterprise integration platforms—hub, mesh-adjacent services, or hybrid iPaaS patterns
• Specify REST or GraphQL APIs with versioning, pagination, filtering, and error contracts
• Author OpenAPI or AsyncAPI specifications and consumer-driven contract tests
• Implement event-driven flows—topics/queues, outbox, idempotent consumers, compensating actions
• Define canonical models, mappings, and anti-corruption layers between bounded contexts
• Stand up API gateways, B2B partner endpoints, webhooks, and transformation/routing rules
• Apply OAuth2/OIDC, API keys, mTLS, and scope models for internal vs external callers
• Plan observability—correlation IDs, trace propagation, structured errors, DLQ operations
• Manage lifecycle—deprecation headers, sunset policy, backward-compatible schema evolution

When NOT to Use

• X12/EDIFACT segment mapping, 997/APERAK, AS2/VAN EDI transport → edi-engineer
• Classified air-gapped build, ATO evidence, cleared pipeline promotion only → classified-software-devsecops-engineer
• VRP, MIP, scheduling, or solver-based optimization → operations-research-algorithm-developer
• Generic application CRUD, UI, or single-service features without integration architecture → senior-software-engineer
• CI/CD pipeline YAML, GitOps, and deploy mechanics only → devops
• Landing zone, VPC, and managed cloud resource design → cloud-engineer
• Enterprise-wide cloud reference architecture and migration roadmap → cloud-architect
• Internal developer platform golden paths and portals → platform-engineer

Related skills

Core Workflows

1. Scope and integration boundaries

Define systems of record, sync vs async boundaries, partner vs internal surfaces, and non-goals.

See `references/enterprise_integration_api_scope.md`.

2. API design and contracts

Model resources, errors, versioning, and publish OpenAPI/AsyncAPI with contract tests.

See `references/api_design_and_contracts.md`.

3. Event-driven reliability

Choose messaging patterns, idempotency keys, outbox, sagas/choreography, and failure handling.

See `references/event_driven_and_reliability.md`.

4. Canonical models and transformation

Define canonical schemas, ACLs, mapping rules, and validation at ingress/egress.

See `references/canonical_models_and_transformations.md`.

5. Security, gateways, and governance

Configure gateways, auth, rate limits, partner onboarding, and policy enforcement.

See `references/security_governance_and_gateways.md`.

6. Operations, observability, and lifecycle

Instrument traces and metrics, operate DLQs, and execute deprecation and compatibility plans.

See `references/operations_observability_and_lifecycle.md`.

Outputs

• Integration context diagram — systems, channels, sync/async, trust zones
• Contract artifacts — OpenAPI/AsyncAPI, JSON Schema, example payloads, error catalog
• Mapping spec — canonical fields, transforms, validation rules, idempotency strategy
• Runbook — replay, DLQ drain, partner cutover, rollback, compatibility matrix
• ADR or decision log — orchestration vs choreography, versioning, auth model

Principles

• Prefer contracts and schemas over tribal knowledge; test consumers in CI
• Make idempotency and deduplication explicit at every external boundary
• Separate partner (B2B) surfaces from internal mesh traffic—different auth, SLOs, and change windows
• Design for observable failures—correlation ID end-to-end, structured errors, actionable DLQs
• Ship backward-compatible changes; document sunsets and give consumers migration time

API design and contracts

Table of contents

1. REST design 2. GraphQL boundaries 3. Versioning 4. OpenAPI and AsyncAPI 5. Errors and pagination

REST design

• Use nouns for resources; HTTP methods express intent
• Prefer stable resource IDs (UUID, partner-scoped keys)—not auto-increment across partners
• Support filtering, sorting, sparse fieldsets for list endpoints; cap page size
• Use 202 Accepted for async work; return Location or job ID for status polling
• Document idempotency via Idempotency-Key header on unsafe retries

GraphQL boundaries

Use GraphQL when:

• Many clients need different field shapes on the same aggregate
• A BFF aggregates multiple backends with strict auth per field

Avoid GraphQL when:

• Partner B2B expects simple REST + OpenAPI and long-term stability
• Heavy batch export or file semantics dominate

Enforce depth limits, query cost, and persisted queries for public/partner APIs.

Versioning

Rules:

• Additive changes only in minor versions
• Breaking changes require new major + sunset on old major
• Publish changelog and consumer notification lead time

OpenAPI and AsyncAPI

OpenAPI (REST):

• Single source of truth in repo; generate server stubs or client SDKs as needed
• Include examples, description, security schemes, and standard error responses
• Lint with Spectral or equivalent in CI

AsyncAPI (events):

• Document channels, payloads, headers (correlation, trace, schema version)
• Bind to actual broker (Kafka, SNS/SQS, etc.) in deployment config—not only prose

Contract testing:

• Provider verifies published contract; consumers run pact-style or schema tests in CI
• Fail build on breaking diff without explicit approval label

Errors and pagination

Standard error body (problem+json or org standard):

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "shipTo.postalCode is required",
  "instance": "/v1/orders/req-abc",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}

Pagination:

• Cursor-based for large, live datasets; offset only for small admin UIs
• Return next link or cursor token; document max page size

For enterprise-wide architecture review → senior-system-architecture.

Canonical models and transformations

Table of contents

1. Canonical model 2. Anti-corruption layer 3. Mapping and validation 4. iPaaS and ESB patterns 5. Reconciliation

Canonical model

A canonical model is the organization’s agreed shape for an entity (e.g., Order, Shipment, Party) independent of any one system’s quirks.

Principles:

• Name fields for business meaning, not source column names
• Use explicit types (money as amount + currency, address as structured object)
• Version canonical schemas (order.v2) separately from API path versions
• Keep identifiers stable across systems (globalCustomerId, partnerOrderId)

Publish canonical schemas (JSON Schema, Avro, Protobuf) in a registry when multiple teams consume them.

Anti-corruption layer

Place an ACL between external/partner models and internal domain models:

Partner payload → ACL validate/map → Canonical → Domain service
Domain event    → ACL map          → Partner format → Gateway

ACL responsibilities:

• Translate enums and code lists (partner SKU → internal SKU)
• Reject or quarantine invalid payloads before domain logic
• Hide legacy quirks from core services (fixed-width codes, nullable sentinels)

Do not leak partner field names into core domain entities.

Mapping and validation

Implement transforms as testable units with golden files per partner profile.

For EDI segment/loop mapping after canonical exists → edi-engineer.

iPaaS and ESB patterns

Orchestration (hub): visual flows, centralized error queues—good for many SaaS adapters.

Choreography (events): domain events between services—good for high-scale internal domains.

Document which flows must use the hub (e.g., all B2B ingress) vs mesh-only (internal high-volume).

Reconciliation

When sync and async paths coexist:

• Define reconciliation jobs (compare counts, checksums, last-modified)
• Log discrepancy cases with correlation ID and payload hash
• Provide operator UI or report for unmatched records

Idempotency and outbox patterns → references/event_driven_and_reliability.md.

Enterprise integration and API scope

Table of contents

1. Role boundaries 2. Integration styles 3. Scoping checklist 4. Deliverable boundaries

Role boundaries

Revalidate scope when a request is only deploy scripts, only EDI segments, or only solver formulation.

Integration styles

Document the system of record per entity (order, customer, inventory) and whether integration is read, write, or bidirectional.

Scoping checklist

1. Stakeholders — product owners, partner ops, security, SRE, data governance 2. Trust zones — internet partner, corporate DMZ, internal mesh, batch zone 3. Channels — REST, GraphQL, Kafka/SQS/SNS, webhook, SFTP (hand off file semantics to owning team) 4. Volume — peak TPS, payload size, burst vs steady, retention 5. Latency SLO — sync p99, async max delivery delay, partner SLA 6. Consistency — strong vs eventual; acceptable duplicate handling 7. Compliance — PII fields, residency, audit log requirements 8. Lifecycle — MVP cutover, dual-write period, deprecation horizon

Deliverable boundaries

Produce artifacts appropriate to phase:

Do not embed secrets, production URLs, or partner credentials in skill outputs or reference examples.

Event-driven integration and reliability

Table of contents

1. Messaging patterns 2. Outbox and transactional messaging 3. Idempotency 4. Sagas and compensation 5. Failure handling

Messaging patterns

Define ordering needs (per aggregate key), retention, and dead-letter policy up front.

Outbox and transactional messaging

Problem: DB commit and message publish must not diverge.

Outbox pattern:

1. Business transaction writes domain row + outbox row in same DB transaction 2. Relay process publishes outbox rows to broker and marks published 3. Consumers process with idempotency

Alternatives: transactional outbox in same service; avoid dual-write without reconciliation.

Idempotency

Every consumer at an integration boundary should support at-least-once delivery.

Store idempotency records with TTL ≥ max redelivery window. Return same response on duplicate HTTP keys.

Sagas and compensation

Choreography: services react to events; no central orchestrator. Fits autonomous domains; requires clear event contracts.

Orchestration: central coordinator issues commands and tracks state. Fits strict workflows and partner SLAs.

At pattern level:

• Define compensating actions (cancel reservation, reverse hold)—not only forward steps
• Use timeouts and escalation when a step does not complete
• Persist saga state for replay and operator visibility

Do not implement distributed 2PC across heterogeneous systems without strong operational justification.

Failure handling

Webhook reliability: verify signatures, enforce timestamp skew, support replay protection (nonce or event ID store).

Operational playbooks → references/operations_observability_and_lifecycle.md.

Operations, observability, and lifecycle

Table of contents

1. Observability 2. Correlation and tracing 3. DLQ and replay 4. Backward compatibility 5. Deprecation 6. Runbooks

Observability

Instrument every integration path:

Dashboards per partner, API, and flow (ingress vs egress). Alert on SLO burn (error budget) not only raw 5xx.

Deploy and pipeline mechanics → devops. Cloud-native wiring → cloud-engineer.

Correlation and tracing

Correlation ID:

• Accept incoming X-Correlation-Id or generate UUID at edge
• Propagate through HTTP headers, message attributes, and log fields
• Return correlation ID in error responses for partner support

Distributed tracing:

• Use W3C traceparent / OpenTelemetry across sync and async
• Link producer publish span to consumer process span via context injection in message headers

DLQ and replay

Never replay to production without dry-run or sampled replay when side effects are irreversible.

Document max replay window aligned with idempotency TTL.

Backward compatibility

Additive changes (safe):

• New optional JSON fields
• New enum values only if consumers ignore unknowns
• New endpoints or topics

Breaking changes (require major version or new topic):

• Removing fields, tightening validation, changing types
• Renaming fields without aliases
• Changing URL paths for partners

Use schema registries with compatibility modes (backward/forward) for events.

Deprecation

1. Announce sunset date in docs and Sunset / Deprecation HTTP headers 2. Monitor traffic to deprecated version; contact remaining consumers 3. Maintain read-only or dual-publish period as agreed 4. Remove only after zero critical traffic and signed partner ack where required

Maintain a compatibility matrix (consumer × API version × status).

Runbooks

Minimum runbook sections:

• Overview — flow diagram, owners, dependencies
• Normal operation — SLOs, dashboards, key metrics
• Failure modes — symptoms, checks, mitigation
• Partner issues — how to trace by correlation ID
• DLQ replay — prerequisites, commands, rollback
• Rollback — previous gateway route or consumer version

For enterprise-wide operational resilience programs → cyber-resilience-engineer (when scope is org-wide, not single integration).

Security, governance, and API gateways

Table of contents

1. Trust zones 2. Authentication patterns 3. API gateway capabilities 4. B2B vs internal 5. Governance

Trust zones

Never expose internal admin or debug routes on partner gateways.

Authentication patterns

Apply least-privilege scopes per partner profile. Rotate credentials on schedule and on incident.

Security program ownership (IdP, KMS, corporate policy) → information-security-engineer.

API gateway capabilities

Configure gateways (Kong, Apigee, AWS API Gateway, Azure APIM, etc.) for:

• Routing — path/host-based to upstream clusters
• Rate limiting — per client ID, per IP, burst + sustained
• Quota — daily/monthly caps for partner tiers
• Request/response transformation — headers, URL rewrites (keep complex logic in ACL services)
• TLS termination and certificate management
• Request validation — OpenAPI validation at edge when appropriate
• Analytics — latency, 4xx/5xx, quota exhaustion

Prefer thin gateway, thick ACL for business rules.

B2B vs internal

Run partner certification before production: contract tests, negative cases, load smoke.

Governance

• API catalog — register every external surface with owner and lifecycle state
• Review gate — security + architecture for new partner integrations
• Standard headers — X-Correlation-Id, traceparent, optional X-Partner-Id
• Data classification — tag payloads; block PII in logs and DLQ dumps
• Exception process — time-boxed waivers with expiry

Classified environments and cleared pipeline boundaries → classified-software-devsecops-engineer.

Pipeline security scanning → devsecops.