api

api is a command-line tool from ReadMe that turns an OpenAPI (or Swagger) definition into a ready-to-use, fully typed TypeScript SDK. Instead of hand-writing request builders and response types for a third-party API, you point npx api install at a spec — a URL, a local file, or a ReadMe API Registry identifier — and it generates a local package with chainable methods for every operation, complete with parameter and response typings derived straight from the schema.

The generated SDK is installed into a .api/ directory and tracked with its own lockfile (api.json), so re-running the installer updates the client the same way npm install updates a dependency. Under the hood, requests are compiled into a HAR payload via @readme/oas-to-har and executed with fetch-har, so the runtime behavior of every generated method stays consistent regardless of which API it targets.

What You Get

• A npx api install <spec> command that fetches, dereferences, and caches an OpenAPI definition from a URL, local path, or ReadMe API Registry UUID
• Codegen that produces a fully typed TypeScript SDK (also usable from plain JS) with one chainable method per operation ID
• An .api/ project directory with a lockfile (api.json) that tracks installed SDKs the same way package-lock.json tracks npm dependencies, including integrity hashes
• Built-in request handling via @readme/oas-to-har + fetch-har, so parameters and payloads are compiled into HAR and executed consistently across every generated client
• CLI subcommands (install, uninstall, list) for managing multiple generated SDKs inside the same project

Common Use Cases

• Generating an internal, typed client for a company’s own OpenAPI/Swagger-documented service instead of maintaining a hand-written fetch wrapper
• Quickly prototyping against a third-party API that publishes an OpenAPI spec, without writing request/response types by hand
• Standardizing how a team consumes multiple internal APIs by generating one consistently-shaped SDK per service
• Consuming APIs published to the ReadMe API Registry directly by UUID shorthand instead of a raw spec URL

Under The Hood

Architecture - The CLI entrypoint (src/bin.ts) parses arguments with Commander and dispatches to subcommands under src/commands/ (install, uninstall, list); a Storage class (src/storage.ts) owns the .api/ project directory and its api.json lockfile (source, integrity hash, installer version, language, identifier per installed SDK), while a Fetcher (src/fetcher.ts) normalizes the install source — public URL, local/relative path, raw spec object, GitHub blob URL rewritten to raw content, or a ReadMe API Registry UUID matched via regex — before handing the dereferenced OpenAPI document to a codegen factory (src/codegen/factory.ts) that currently targets a single SupportedLanguages.JS TypeScript generator (src/codegen/languages/typescript/) which emits one chainable method per operation ID plus JSON-Schema-backed types.

Tech Stack - TypeScript on Node >=20.10, built with tsc/tsup in an npm-workspaces monorepo (packages/api, packages/core, packages/httpsnippet-client-api, packages/test-utils) orchestrated by Turborepo and versioned with Changesets; core dependencies are oas/oas-normalize for spec parsing, @readme/oas-to-har for compiling requests into HAR, commander for CLI parsing, ts-morph for TypeScript AST generation, and ora/chalk/update-notifier for CLI UX.

Code Quality - Vitest covers the CLI surface with 11 test files including test/bin.test.ts, test/storage.test.ts, test/fetcher.test.ts, test/router.test.ts, per-command tests under test/commands/, and codegen tests including a dedicated TypeScript smoke test; the project also runs knip (unused-code detection), tsc --noEmit for type checking, and oxlint/oxfmt for linting/formatting as part of its lint script, indicating an actively enforced quality bar.

API Design - The generated consumer-facing API (const petstore = require('@api/petstore'); petstore.listPets()) is deliberately minimal — one promise-returning method per OpenAPI operation ID, importable via both CJS and ESM — while the CLI itself (api install, api uninstall, api list) follows familiar package-manager verb conventions; documentation is unusually thorough for a dev tool, with a dedicated docs site (api.readme.dev) covering installation, authentication, parameters/payloads, server configuration, and an explicit ‘how it works’ explainer of the caching and codegen pipeline.