home / skills / velcrafting / codex-skills / integration-adapter

integration-adapter skill

safe

This skill helps you implement a robust external API adapter with timeouts, bounded retries, idempotency, and error mapping for reliable integrations.

npx playbooks add skill velcrafting/codex-skills --skill integration-adapter

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.7 KB

---
name: integration-adapter
description: Build an external API adapter with timeouts, retries, idempotency, and error mapping.
metadata:
  short-description: External adapter + reliability policy
  layer: backend
  mode: write
  idempotent: false
---

# Skill: backend/integration-adapter

## Purpose
Integrate with an external service via a dedicated adapter that enforces:
- timeouts
- retry policy
- idempotency where applicable
- error mapping into shared taxonomy
- observability (logs/metrics/traces) consistent with repo standards

This skill prevents “HTTP calls sprinkled everywhere.”

---

## Inputs
- External API/service name + base URL (or SDK)
- Required operations (list)
- Auth mechanism (token, key, oauth) WITHOUT secrets
- Expected failure cases (timeouts, rate limits, invalid responses)
- Repo profile (preferred): `<repo>/REPO_PROFILE.json`

---

## Outputs
- Adapter module with a narrow interface
- Retry/timeout configuration
- Error mapping to shared taxonomy
- Contract tests or mocks (preferred)
- Minimal observability instrumentation

---

## Non-goals
- Implementing domain rules (use `backend/domain-logic-module`)
- Building orchestration/jobs (use `backend/job-worker-orchestration`)
- Storing secrets in code

---

## Workflow
1) Create adapter boundary:
   - `ExternalServiceClient` or module functions
2) Implement calls with:
   - explicit timeouts
   - bounded retries (with backoff) where safe
   - idempotency keys when supported/needed
3) Normalize errors:
   - map external errors to internal taxonomy
4) Add contract tests/mocks:
   - validate request construction
   - validate response parsing and error handling
5) Add basic observability:
   - correlation id propagation if present
6) Run validations per profile.

---

## Checks
- Adapter is the only place external calls exist for this integration
- Timeouts are explicit
- Retry policy is bounded and safe (no infinite loops)
- If retries, backoff, rate limiting, or multi-step external workflows are introduced,
 - recommend `system/state-machine-mapper` to model external interaction states explicitly.

- Errors map to internal taxonomy
- Tests cover:
  - success
  - timeout or retry scenario
  - bad response parsing

---

## Failure modes
- Retry safety unclear → default to no retry and document why.
- Rate limits encountered → add backoff and respect headers if available.
- External contract unstable → increase mocking/contract tests and tighten parsing.
- Retry/backoff logic added without explicit state modeling →
  require `system/state-machine-mapper` before shipping.

---

## Telemetry
Log:
- skill: `backend/integration-adapter`
- service: `<name>`
- retries: `none | bounded`
- timeout

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

FAQ

Should I always enable retries?

No. Default to no retry when safety is unclear. Enable bounded retries only for operations that are idempotent or safe to repeat and document the rationale.

Where should secrets live?

Do not store secrets in code. Use your platform's secret store or environment configuration and pass non-secret auth metadata into the adapter.