URL shaping

A stitch builds its URL from an RFC 6570 URI template plus the params and query you pass at call time. Simple {id} interpolation is the common case; the full operator set is there when you need it.

Absolute url vs relative path

How you spell the endpoint decides whether a shared baseUrl applies:

• path is relative and is joined onto baseUrl — the origin a stitch inherits from a seam or a shared fragment. Reach for it whenever many stitches share one host.
• url is the complete endpoint (host included). It is templated and query-aware just like path, but it ignores baseUrl — setting url means "this stitch addresses itself." Reach for it for a one-off endpoint.

import { stitch } from 'stitchapi';

// `path` is relative → it joins `baseUrl` (typically shared via a seam or fragment).
const getUser = stitch({
    baseUrl: 'https://api.example.com',
    path: '/users/{id}',
});
await getUser({ params: { id: 1 } });
// → GET https://api.example.com/users/1

[!WARNING]

A relative url is not joined to baseUrl. url: '/users/{id}' overrides the base and resolves to the bare /users/{id}, which isn't fetchable — it fails at call time with a StitchConfigError ("request URL … is not absolute"). When you mean "relative to baseUrl", use path, not url.

Path templates

import { stitch } from 'stitchapi';

const getUser = stitch('https://api.example.com/users/{id}');

await getUser({ params: { id: 1 }, query: { expand: 'roles' } });
// → GET https://api.example.com/users/1?expand=roles

Template variables are filled from params; params, query, headers, and body all travel in one input object. The RFC 6570 operators:

Query serialization

The query builder serializes nested objects and arrays qs-style:

import { stitch } from 'stitchapi';

const search = stitch('https://api.example.com/users');

await search({ query: { filter: { type: 'admin' }, ids: [1, 2] } });
// → /users?filter[type]=admin&ids[0]=1&ids[1]=2

Array encoding is configurable with arrayFormat — indices (the default shown above), brackets, or repeat.

[!NOTE]

Values are percent-encoded with encodeURIComponent, so a space in a query value goes on the wire as %20, not + like URLSearchParams. Both decode to a space server-side; see Migration notes if a byte-for-byte fixture trips on it.

Query defaults in the path

Query keys can be baked into the path string; call-time query merges over them, so a stitch can carry sensible defaults that each call selectively overrides:

import { stitch } from 'stitchapi';

const findUsers = stitch('https://api.example.com/users?sort=name&type=admin');

await findUsers({ query: { type: 'user' } });
// → /users?sort=name&type=user

See also