integration-adapter_skill

Overview

This skill helps build a focused external API adapter that centralizes all outbound calls and enforces timeouts, retries, idempotency, and error mapping into a shared taxonomy. It produces a narrow client interface, config for retry/timeouts, basic observability, and contract tests or mocks. The goal is deterministic, testable integration code and to avoid HTTP calls scattered across the codebase.

How this skill works

You define the external service, operations, and auth (without embedding secrets). The adapter implements calls with explicit timeouts, bounded retries and backoff when safe, and idempotency keys where appropriate. It normalizes external errors into the internal taxonomy and emits minimal logs/metrics/traces with correlation propagation. Contract tests or mocks validate request shape, parsing, and error handling.

When to use it

• Integrating any external HTTP API or SDK where reliability and observability matter
• When you need a single place to control timeouts, retries, and idempotency policies
• If multiple parts of the codebase will call the same external service
• When you need consistent error mapping into an internal error taxonomy
• Before adding backoff or multi-step workflows that may require explicit state modeling

Best practices

• Keep all external calls inside the adapter boundary so callers stay domain-focused
• Use explicit per-call timeouts; prefer no retry by default and document why retries are safe
• Apply bounded retries with exponential backoff only for idempotent or safe operations
• Map external errors to internal taxonomy and surface high-level categories (timeout, rate_limit, transient, permanent)
• Add lightweight observability: logs with skill/service/retries/timeouts and propagate correlation IDs
• Provide contract tests or mocks that cover success, retry/timeouts, and bad responses

Example use cases

• Payment gateway client that uses idempotency keys for safe retry of charge requests
• Third-party catalog service adapter with short timeouts and bounded retries for transient failures
• Rate-limited API client that respects Retry-After headers and maps 429 to a rate_limit error
• Notification provider integration that normalizes diverse error shapes into a unified set of retryable vs permanent errors
• Adapter for an unstable partner API with contract tests and strict parsing to avoid silent failures