API Wrapper Scaffolder

A good API wrapper makes the annoying parts of HTTP someone else's problem exactly once: authentication, pagination, retries, rate limits, and error translation live in one layer, and the rest of the codebase calls typed methods that read like the domain. This skill scaffolds that layer from an API's documentation, a spec file, or a handful of example requests, in whatever language the host project already uses.

When to use this skill

• A project calls a third-party HTTP API with raw requests scattered across many files
• You are integrating a new API and want the client layer designed before the first feature uses it
• An existing wrapper has grown inconsistent: some methods retry, some do not, errors leak raw payloads
• You have API documentation or a spec and want a typed client generated with judgment, not just codegen

Workflow

1. Inventory the surface. From the docs or example calls, list every endpoint the project actually needs — not every endpoint that exists. Wrap demand, not supply.
2. Design the transport core first. One private function owns: base URL, auth injection, timeouts, retry policy (idempotent methods only, exponential backoff with jitter, honor any retry-after header), and response decoding. No public method builds a request by hand.
3. Translate errors at the boundary. Map HTTP outcomes to a small typed hierarchy: AuthError, NotFound, RateLimited(retry_after), ValidationError(fields), ServerError, TransportError. Callers should never parse a status code.
4. Make pagination invisible. Expose iterators or generators that fetch pages lazily, and keep a *_page() escape hatch for callers who genuinely need raw page control.
5. Type the domain objects. Define models for the resources you consume, tolerating unknown extra fields — APIs add fields without warning, and a wrapper that crashes on additions is a liability.
6. Name methods after the domain, not the URL. client.invoices.list(status="open"), never client.get("/v2/invoices?status=open").
7. Write the tests that document behavior: one happy path per method against recorded or stubbed responses, plus a transport suite — retry-then-succeed, rate-limit backoff, auth failure, malformed response body.
8. Ship a usage section with three examples: authenticate, list with pagination, and handle one specific error type.

Output format

Scaffold as a small package, adapted to the host language's conventions:

<api>_client/
  client        # public entry: configuration + resource namespaces
  transport     # request core: auth, retries, timeouts, decoding
  errors        # typed error hierarchy
  models        # resource types with tolerant decoding
  resources/    # one module per resource: invoices, customers, ...
  tests/        # transport behavior + one happy path per method

Guardrails

• Secrets come from configuration, never literals — and never appear in logs or error messages
• Retries only on idempotent requests, unless the API documents an idempotency-key mechanism; if it does, the wrapper uses it
• Every request has an explicit timeout; a wrapper without timeouts is an outage amplifier
• Do not wrap endpoints nobody calls; dead surface area still costs review and upgrades
• Log method, path, status, and duration — never full request or response bodies by default
• The API version (base URL or version header) is pinned in exactly one place

Worked example: wrapping a paginated list

Given GET /v2/invoices?cursor=... returning {data: [...], next_cursor}:

• resources/invoices.list(status=None) returns a lazy iterator; exhausting a page triggers one transport call with the stored cursor
• A 429 during iteration sleeps per the retry-after value, then resumes the same cursor — the caller's loop never notices
• The tests assert: two pages stitch seamlessly, no page is fetched twice, and a mid-iteration AuthError surfaces immediately rather than being retried

If application code ever contains a while loop over cursors, the wrapper has failed its one job.