Notes on API stitching, agent-native integrations, and cutting AI cost.
Oleksandr Zhuravlov
Screens, routes, databases, untrusted input — every boundary in a web app has a library that owns it, except outbound calls to other people's APIs. Why every project still hand-builds that layer, and what changes when you declare it instead.
Oleksandr Zhuravlov
An agent that has never seen StitchAPI hand-rolls fetch and rediscovers your conventions every session. One committed rule — written by npx stitch init — teaches it the habit for the price of a ~300-token file it reads once, instead of the ~115k-token docs corpus or a repo-exploration detour it pays every time.
Oleksandr Zhuravlov
Sometimes the schema you validate against shows up at runtime — you fetch it, a tenant registers it, a config push delivers it — as JSON Schema you didn't have when you compiled. You can't generate types for it; validate the incoming data at the boundary instead, and return structured errors the sender can act on.
Oleksandr Zhuravlov
When API calls do not depend on each other, running them as a ladder of awaits is wasted latency — and Promise.all drops the trace, the cancellation, and the per-call resilience. all, any, and race run independent stitches concurrently as one traced, fail-fast group, and because each returns the same callable shape a stitch does, they nest.
Oleksandr Zhuravlov
Wrap one endpoint as a stitch, leave the rest of your fetch and axios code untouched, and grow the typed-resilient surface one call at a time.
Oleksandr Zhuravlov
A model call is just an HTTP request, so wrapping it in an SDK buys you a dependency, a bespoke client, and a rewrite every time you switch providers. Declare the call as a stitch and switching models is a one-line change.
Oleksandr Zhuravlov
A stitch turns one endpoint into a typed resilient function; the adapter underneath decides how the bytes move. Here's how to pick fetch, axios, or xhr — and when to write your own.
Oleksandr Zhuravlov
A dependent chain — an order, then its shipment, then the carrier tracking — wants typed intermediate values and one linked trace, not three unrelated calls. linked() opens a run scope so you write the plain awaits you would anyway: ancestors stay typed variables, and the whole sequence shares one trace and fails fast.
Oleksandr Zhuravlov
Codegen consumes an OpenAPI document to build a client. Run it the other way: emit an OpenAPI 3.1 spec from the stitches you already declared, so the teams and tools that still need a spec get one without the stitch stopping being the source of truth.
Oleksandr Zhuravlov
fetch has no timeout option, so a hung request blocks your caller forever. This shows the AbortSignal.timeout pattern that actually cancels the socket, the Promise.race trap that doesn't, and how a stitch declares total and per-attempt deadlines that compose with retry.
Oleksandr Zhuravlov
A write can time out after the server committed but before the response reaches you, so the retry charges the card twice. An idempotency key lets the server collapse the duplicate.
Oleksandr Zhuravlov
The axios.create() is the small part of a mature setup — the bulk is interceptors: retry-with-backoff, a 401 refresh, baseURL, validateStatus, manual typing. Migrate that layer onto a stitch, keeping or dropping axios.
Oleksandr Zhuravlov
Your fetch call works until the API blips: no retry, no timeout, no validation, and the JSON is typed `any`. Here is the same call as a stitch, field by field, and how each line of glue becomes a declaration.
Oleksandr Zhuravlov
Orval turns an OpenAPI spec into a typed client, TanStack Query hooks, Zod schemas, and MSW mocks in one command. This compares that generate-everything-from-a-spec model against declaring endpoints one at a time and validating the live response — and names exactly when each wins.
Oleksandr Zhuravlov
CSV reports, HTML pages, PDFs, and zips do not fit a JSON client. A stitch reads them too: responseType picks the decode, transform reshapes the body, and an output schema validates the value you actually use.
Oleksandr Zhuravlov
Most HTTP clients drag a node: import that breaks on a Worker. StitchAPI core is Web-API only, so the same stitch runs unchanged on Cloudflare Workers and Deno — and a KV-backed store shares its cache and auth across isolates.
Oleksandr Zhuravlov
You have a curl line from the API docs and a token in your shell. Paste it into stitch from-curl and get back a typed stitch declaration with the credential turned into an env() placeholder — never the literal secret.
Oleksandr Zhuravlov
You already run TanStack Query for view state. Drop a stitch in as the queryFn and the call gains types, validation, retries, and auth — no glue code.
Oleksandr Zhuravlov
Code that calls APIs you do not own goes slow and flaky in tests. A stitch gives you two clean seams: inject a mock adapter and run the real engine, or stub the stitch when only the caller is under test.
Oleksandr Zhuravlov
Logging your outbound calls usually means your logs now carry Authorization headers, tokens in URLs, and full PII bodies. StitchAPI tracing is off by default and redacts secrets before anything is written.
Oleksandr Zhuravlov
A type-safe API client usually means generating TypeScript types from an OpenAPI document and importing a typed fetch wrapper like openapi-fetch. This shows the other path — declare one endpoint, hand it a Zod schema, and get types plus runtime validation with no generated artifact to commit or regenerate.
Oleksandr Zhuravlov
A thrown error is typed `unknown`, so every catch block re-narrows before it can read a status. Call a stitch with .safe() and branch on a discriminated union where the failure arm is already a StitchError.
Oleksandr Zhuravlov
A GraphQL endpoint can answer HTTP 200 and still have failed. A graphql() stitch posts the operation, treats a 200-with-errors as a failure, and hands back the validated data — no client, no codegen.
Oleksandr Zhuravlov
Collecting every page of a cursor- or offset-paginated API in TypeScript means a while loop, cursor bookkeeping, and a concat you write by hand. This shows that loop, where it gets fragile under retries and rate limits, and how a stitch declares next and items so one await follows every page with auth, retry, and throttle applied per page.
Oleksandr Zhuravlov
fetch cannot report how many bytes have left the machine, so a 50MB upload looks frozen. Declare a multipart upload on xhrAdapter, pass onProgress per call, and drive a real bar from the bytes sent.
Oleksandr Zhuravlov
The standard way to validate an API response with Zod is to parse the JSON through a schema with safeParse at the call site. This shows that pattern and its rough edges, then how to declare the same schema on a stitch so every call validates its response — and its input — at the boundary with a typed error.
Oleksandr Zhuravlov
Schema drift is when an API's response shape changes after you've written code against it, while your types and tests keep passing. This defines the term, names the kinds of drift, and shows how to detect each one by diffing the live response against the schema you already declared.
Oleksandr Zhuravlov
People leave axios for two unrelated reasons — they want a lighter fetch wrapper, or they're tired of maintaining the retry/timeout/auth/validation glue around every call. Those point at different tools. Here's an honest map of the alternatives, and where a stitch fits.
Oleksandr Zhuravlov
Tool calling hands the model one schema per endpoint and re-sends every one each turn; code mode hands it a small typed API and lets it discover the rest on demand. Here's what the two patterns actually are, and how StitchAPI exposes code mode as three fixed tools.
Oleksandr Zhuravlov
Rate (calls per unit time) and concurrency (in-flight cap) are different controls, and the usual setTimeout queue breaks the moment a second call site or process shares the limit. Here's how to pace calls correctly in TypeScript, and how a stitch declares it as data.
Oleksandr Zhuravlov
Native fetch has no retry, and the while-loop everyone copies retries the wrong things — non-idempotent writes, dead 4xx, no backoff. Here's a correct hand-rolled retry in plain TypeScript, the four pitfalls it has to dodge, and the one-line declarative version.
Oleksandr Zhuravlov
StitchAPI attacks AI cost on two axes — the tokens you spend describing tools to a model, and the redundant upstream calls your agents make. Here's the mechanism behind each.
Oleksandr Zhuravlov
The one-tool-per-endpoint pattern re-sends every endpoint's JSON schema on every turn of an agent loop. Here's why that cost compounds, and how code-mode keeps the standing context flat as your catalog grows.
Oleksandr Zhuravlov
When an AI agent is the caller, raw fetch() is the wrong primitive — it leaks the credential, returns unvalidated bytes, and has no retry, throttle, timeout, or trace. Here's the case for handing the agent a stitch instead.
Oleksandr Zhuravlov
Handing an agent your API key leaks the secret into prompts, logs, and traces. StitchAPI keeps the credential behind the seam — the caller gets the ability to make one call, never the key itself.
Oleksandr Zhuravlov
A third-party field quietly changes shape and your code keeps compiling, your tests keep passing, and the breakage only shows up live. Here's how leveled drift detection turns that silent failure into a visible signal.
Oleksandr Zhuravlov
How StitchAPI's read-through cache and in-process request coalescing actually work — the derived, principal-scoped cache key, the coalescing window, and what's safe to put behind them.
Oleksandr Zhuravlov
Most clients only find a rate limit by hitting it. A declared throttle keeps you under the limit instead — here's the difference between a rate cap and a concurrency cap, and how it composes with the reactive retry path.
Oleksandr Zhuravlov
When an upstream dependency is already down or crawling, naive retries make its outage yours. Here's how a circuit breaker plus layered timeouts turn that failure mode into a bounded, declared policy.
Oleksandr Zhuravlov
The same stitch declaration is callable as an in-process function, a CLI command, an HTTP endpoint, and an MCP tool — no rewrite, and the resilience, auth, and drift you declared once apply identically through all four.
Oleksandr Zhuravlov
Spec-based generators turn an OpenAPI document into a fully typed client. Runtime stitching turns a single URL into a validated function. Here's an honest, axis-by-axis comparison — and when each one is the right call.
Oleksandr Zhuravlov
The reflex when wiring an agent to a service is to stand up a dedicated MCP server for it. Here's the cost of N servers, when one runtime exposing many stitches is the better shape, and when a bespoke server still wins.
Oleksandr Zhuravlov
Hosted workflow platforms and a library like StitchAPI solve overlapping but different problems. A neutral comparison on deployment model, where the logic lives, operational surface, and the unit of work — including when each is the better fit.
Oleksandr Zhuravlov
Take a streaming stitch and expose it as a text/event-stream Response from a Next.js App Router route handler with @stitchapi/next, then consume the deltas on the client.
Oleksandr Zhuravlov
How to hand a model a stitch as a callable tool with @stitchapi/vercel-ai — so it gets typed, validated data while the credential stays behind the seam, and your declared resilience comes along for free.
Oleksandr Zhuravlov
A throttle that's correct on one process quietly multiplies by N when you scale out, and per-process logins re-authenticate on every worker. StitchAPI's pluggable state store moves both into shared storage so the limiter and cookieSession coordinate fleet-wide.
Oleksandr Zhuravlov
The same stitch plugs into each major UI framework via a thin binding, surfacing loading, error, drift, and streaming as idiomatic reactive state. Here's the shared core that makes that consistent.