External API Adapters

Use this skill when code crosses a process or vendor boundary.

Core Rules

• Keep external APIs behind adapters. Domain and use case code should depend on ports, not SDKs or HTTP client details.
• Convert external DTOs into internal domain/application types at the boundary.
• Normalize external errors into a small set of application errors.
• Set explicit timeouts for every network call.
• Make retry behavior deliberate, bounded, and safe for the operation.
• Capture correlation IDs, request IDs, vendor IDs, and pagination cursors as structured evidence.
• Keep credentials and raw sensitive payloads out of logs, snapshots, and thrown messages.

Adapter Shape