Design a resilient integration with a third-party API handling failures, limits, secrets, and data mapping.
## CONTEXT I am integrating my system with a third-party API in 2026 (payments, messaging, data, AI, etc.) and want a resilient, maintainable integration rather than naive direct calls scattered through my code. External APIs fail, rate-limit, change, and have inconsistent data models, so a robust integration needs an anti-corruption layer, retry and circuit-breaker logic, idempotency, secret handling, and a strategy for staying in sync as their API evolves. The integration is a dependency I do not control, so the design must contain its blast radius and keep my domain model clean. ## ROLE Act as an integration engineer who has wired up dozens of third-party APIs and been burned by every one of them. You design defensively, isolate the vendor, and never let an external quirk leak into the core domain. ## RESPONSE GUIDELINES - Start with an architecture sketch placing an anti-corruption layer between my domain and the vendor. - Treat the vendor as unreliable and design every interaction for failure. - Keep vendor-specific data shapes out of my core model; map at the boundary. - Address secrets, retries, idempotency, and observability concretely. - Plan for the vendor changing or going down, not just the happy path. ## TASK CRITERIA ### 1. Boundary & Anti-Corruption Layer - Design an adapter that translates vendor models to my domain model. - Isolate all vendor SDK/HTTP details behind a stable internal interface. - Define how vendor enums, IDs, and quirks are normalized. - Make the integration swappable in case I change vendors. ### 2. Resilience & Failure Handling - Implement retries with backoff for transient errors only, with idempotency. - Add circuit breaking and timeouts to contain vendor outages. - Define fallback or degraded behavior when the vendor is unavailable. - Handle partial failures and reconciliation for multi-step operations. ### 3. Rate Limits & Throughput - Respect the vendor's rate limits proactively, not just reactively on 429s. - Queue or throttle outbound calls to stay within quotas. - Batch requests where the vendor supports it to reduce calls. - Handle bursty workloads without tripping vendor limits. ### 4. Secrets, Auth & Security - Securely store and rotate API keys/OAuth credentials for the vendor. - Verify vendor webhooks/callbacks if the integration is bidirectional. - Avoid logging secrets or sensitive vendor payloads. - Address data-residency and PII implications of sending data out. ### 5. Sync, Observability & Maintenance - Design data synchronization (polling, webhooks, or both) and reconciliation. - Add metrics, tracing, and alerting specific to vendor health. - Plan for vendor API versioning and deprecation handling. - List integration anti-patterns (tight coupling, silent retries) to avoid. ## ASK THE USER FOR - The third-party API and the operations you need from it. - Its auth model, rate limits, and whether it offers webhooks. - How tolerant your use case is to vendor downtime or latency. - Data sensitivity and any compliance constraints on sending data externally.
Or press ⌘C to copy