rejifald/StitchAPI

📚 stitchapi.dev — documentation, guides & live playground
Zero runtime dependencies · ~21 kB min+gzip — a typical import { stitch } tree-shakes to ~19 kB, and with no transitive tree there is nothing else to install or audit. The cache engine and the OTLP exporter load lazily, on first use, so they are not in those figures. The size is an enforced budget in CI , not an aspiration.
Verifiable supply chain — every package publishes from GitHub Actions over OIDC with a signed npm build-provenance attestation , so you can confirm which commit and which workflow produced the tarball you installed. Each release also ships an SBOM in both SPDX and CycloneDX, and the repo is scored publicly by OpenSSF Scorecard .
Watch more
> [!NOTE]
>
> **StitchAPI is at 1.0.0-rc.8.** The core runtime is feature-complete, zero-dependency, covered by a green test gate, and already running in production in two projects. We're validating in the wild before stamping a stable 1.0.0 — pin an exact version and expect only small, documented changes. Feedback is welcome.
---
Table of Contents
- What is a stitch?
- Motivation
- Why StitchAPI
- What StitchAPI is not
- Features
- Install
- Quick start
- Composition: seam, extends, .with()
- Validation & leveled drift
- Resilience: retry, throttle, timeout
- Caching
- Auth as a boundary
- Surfaces: any request style
- Four front doors
- Agent-native
- Errors & pitfalls
- Zero-infra observability
- Packages
- Documentation
- Contributing
- License
What is a stitch?
A **stitch** is StitchAPI's core primitive: it takes a single endpoint and hands back a callable. You declare the contract once — input, output, auth, resilience — and call it like a local function. The same definition your code calls, the CLI runs and an AI agent invokes — and every caller gets a **capability, not a credential**. A service with more than one endpoint is a **seam** — a group of stitches that share a base URL, auth, and one runtime (throttle budget, store, trace sink).
Keep the fetch or axios you already have — it's the adapter underneath. A stitch sits _above_ the transport and turns an endpoint into a function rather than replacing the call.
Motivation
In almost every project there's a src/api/ folder of thin functions that fire an HTTP request and pull the payload out of the response. Everything that actually makes an integration reliable — auth lifecycle, retries, rate limits, timeouts, response validation, drift detection, observability — gets re-implemented at every call site, and each wrapper rots independently. fetch hands back opaque bytes, and raw bytes aren't what application code (or an AI agent) needs; both want structured, validated, observable results.
A stitch folds all of that back into the call:
| Around raw fetch, you hand-roll… | …a stitch declares it once |
| --------------------------------------------------- | ------------------------------------------------------------- |
| Opaque bytes you parse and hope are the right shape | Schema-validated, typed results — drift caught on every call |
| A throw on the first failure, then it's on you | Retries with backoff + jitter, honoring Retry-After |
| One coarse timeout, if you remember it | Layered total / per-attempt timeouts with real aborts |
| No rate control — you meet the 429s in production | Proactive throttle: rate + concurrency caps, shared per host |
| A raw byte stream you frame and paginate yourself | SSE framing, delta concatenation, auto-pagination |
| Zero visibility into what the call did | A typed event stream + opt-in traces: latency, retries, drift |
Why StitchAPI
There are plenty of ways to get a typed API client — spec-based generators, hand-authored contract clients, workflow platforms, or a folder of hand-rolled fetch wrappers. StitchAPI sits in a spot none of them cover: it turns **one endpoint at a time** into a resilient, validated, observable function — no spec, no codegen, no config files, no server; only explicit composition.
- **Atomic, not spec-first.** Spec-based generators (openapi-generator, Orval, Kubb, …) need a complete OpenAPI document first — and most real-world APIs (internal, undocumented, the long tail) never get one. A stitch needs a URL and one example response.
- **A runtime, not a code generator.** No generated SDK to commit, diff, and regenerate. The declaration _is_ the client, validated on every live call — so a silently renamed field is a loud, leveled **drift** signal, not an undefined three layers downstream.