claudekit/skills/api-client/SKILL.md

name, description

name	description
api-client	Use when setting up axios, fetch, or httpx clients, implementing request interceptors, adding retry logic, handling authentication tokens, or generating type-safe API clients from OpenAPI specs. Also activate whenever code makes HTTP requests, integrates with external APIs, or needs robust error handling for network calls.

API Client Patterns

When to Use

• Setting up HTTP clients (httpx, axios, fetch) with base URLs and default headers
• Implementing request/response interceptors for auth tokens, logging, or error transformation
• Adding retry logic with exponential backoff for transient failures
• Generating type-safe API clients from OpenAPI specifications
• Handling authentication tokens (Bearer, API key) in outbound requests
• Building wrapper classes around third-party REST APIs

When NOT to Use

• Building API servers (use backend-frameworks)
• Making simple one-off HTTP calls that don't need a configured client
• GraphQL clients (use Apollo or urql documentation directly)

---

Quick Reference

Topic	Reference	Key content
All client patterns	references/patterns.md	httpx, axios, fetch wrappers, interceptors, retry, type-safe clients
HTTP client recipes	references/http-client-patterns.md	Advanced patterns, streaming, file uploads

---

Best Practices

1. Create a single configured client instance. Don't construct new clients per request. Configure base URL, timeouts, and default headers once.
2. Set explicit timeouts. Never use default (infinite) timeouts. Set connect and read timeouts separately.
3. Use interceptors for cross-cutting concerns. Auth token injection, request logging, and error transformation belong in interceptors, not in each call site.
4. Implement retry with exponential backoff and jitter. Only retry idempotent requests (GET, PUT, DELETE) and transient errors (5xx, network errors).
5. Respect Retry-After headers. When the server sends Retry-After, honor it instead of using your own backoff schedule.
6. Generate clients from OpenAPI specs. Use openapi-typescript + openapi-fetch (TypeScript) or openapi-python-client (Python) for type-safe API consumption.
7. Handle errors at the boundary. Transform HTTP errors into domain-specific errors at the client wrapper level.

Common Pitfalls

1. No timeout configured — requests hang indefinitely on unresponsive servers.
2. Retrying non-idempotent requests — retrying POST can create duplicates. Use idempotency keys.
3. Swallowing error details — wrapping errors without preserving the original status code and message.
4. Token refresh race conditions — multiple concurrent requests all try to refresh the token simultaneously. Use a mutex/lock.
5. Not closing client connections — httpx AsyncClient and axios instances should be properly closed/disposed.

---

Related Skills

• error-handling — Error transformation and retry patterns
• authentication — Token management for API calls
• backend-frameworks — Building the APIs these clients consume