api-client

API Client

Integrate the needed API operation with a small, testable boundary. Prefer an existing CLI or maintained SDK when it satisfies the contract; xh owns endpoint inspection and provider skills own their existing clients.

Workflow

1. Choose the seam: reuse the project's client and sync/async model. Otherwise use HTTPX through uv with one owned client lifetime, explicit timeouts and pool limits, and typed request/response boundaries. Avoid a generic SDK framework for one endpoint.
2. Bound the operation: cap pages, records, response bytes, concurrency, attempts, and elapsed time according to configuration. HTTPX read timeouts bound inactivity, not the total duration; enforce the operation's overall deadline separately.
3. Control traversal: stop on terminal or repeated cursors, and report partial results explicitly when a limit is reached. Validate provider-returned next URLs before following them; do not send credentials to a new origin or follow redirects implicitly.
4. Retry by meaning: retry only documented transient failures within the total deadline. Honor valid Retry-After; if waiting would exceed the remaining deadline, report exhaustion instead of retrying early. Otherwise use bounded backoff with jitter. Keep authentication, permission, validation, and malformed-success failures visible.
5. Reconcile writes: reuse a stable provider-supported idempotency key for the same logical write. After a timeout or lost response, read authoritative operation state before retrying; without safe reconciliation or documented idempotency, return an explicit unknown outcome.
6. Verify offline first: exercise the HTTPX test boundary, including limits and failures; then perform only the live reads or writes authorized for this integration. Poll asynchronous jobs with a bounded deadline and verify their terminal result.

Gotchas

• Transport retries skip status codes: HTTPX transport retries cover only failed connects (ConnectError, ConnectTimeout); they do not implement status-code retries or safe replay of an uncertain write.
• Bound streams while reading: enforce byte limits while reading and always close responses and clients, including cancellation paths. Checking size after buffering is not a memory bound.
• Route credentials deliberately: keep TLS verification enabled and make proxy/environment behavior deliberate. Validate base URLs at the configuration boundary; log only redacted endpoint identities.
• Never disguise errors as empty: an empty list must mean no records, not a swallowed 403, exhausted page budget, or failed parse. Preserve the original exception cause without including secrets.