coder-system-design-external-api

<when_to_use> Integrating third-party APIs or partner services Designing resilience around network and provider failures Handling provider limits, auth lifecycle, and contract evolution </when_to_use>

<input_requirements> Provider SLA/SLO and rate limit policy Auth method and credential lifecycle constraints Error model and retry semantics from provider docs Business criticality and degradation tolerance </input_requirements>

<integration_workflow> Document provider contract, limits, and deprecation policy Define timeout budget and retry eligibility matrix Implement resilience layer (timeouts, retries, circuit breaker, limiter) Add idempotency and duplicate submission controls for mutations Add observability, alerts, and runbooks before rollout Verify compatibility continuously with contract checks </integration_workflow>

<reliability_patterns> Use bounded retries with exponential backoff and jitter for transient failures only Use circuit breaker with half-open probing to prevent cascade failures Use client-side throttling and respect 429 plus Retry-After semantics Use graceful degradation or fallback for non-critical dependency paths Use async decoupling where provider latency is highly variable </reliability_patterns>

<security_controls> Use least-privilege scopes and short-lived credentials where possible Automate secret rotation, revocation, and audit logging Protect token refresh flows and enforce strict validation Prevent secret leakage in logs, traces, and error payloads </security_controls>

<quality_rules> No external call path is accepted without explicit timeout No mutating operation is accepted without idempotency plan No retry policy is accepted without limits and jitter No provider integration is accepted without observability signals and alerting </quality_rules>

<do_not> Do not apply retries blindly to all errors Do not ignore provider deprecation/change notices Do not keep long-lived static credentials without rotation </do_not>

<output_requirements> Integration architecture and failure-mode strategy Timeout, retry, and rate-limit policy summary Security controls and secret lifecycle plan Monitoring signals, SLO impact, and runbook pointers </output_requirements>