URL helpers

Base URL

Set a base URL for requests using the baseURL option:

import { createFetchClient } from "@zayne-labs/callapi";

const callBackendApi = createFetchClient({
	baseURL: "https://api.example.com",
});

const { data } = await callBackendApi("/users/123/posts");

The resolved URL will be: "https://api.example.com/users/123/posts"

CallApi handles the joining slash. Absolute URLs ignore baseURL.

Dynamic Parameters

Many URLs contain dynamic parts representing specific resources, like an ID. For example, /users/123 fetches user 123, and /posts/456 fetches post 456.

Instead of building the URL yourself, use :param or {param} placeholders. For example, /users/:userId and /users/{userId} both accept a userId value from params.

Provide values for these placeholders using the params option. CallApi replaces each placeholder with its matching value.

The params option accepts either an object or an array:

• Object: Keys match the parameter names without : or braces. For example, /users/:userId/posts/{postId} with params: { userId: 123, postId: 456 } resolves to /users/123/posts/456.
• Array: The values replace the parameters in the order they appear in the URL. For example, if your URL is /users/:userId/posts/:postId, passing params: ['123', '456'] will result in /users/123/posts/456.

import { callApi } from "@zayne-labs/callapi";

const { data } = await callApi("https://api.example.com/users/:userId/posts/{postId}", {
	params: {
		userId: 123,
		postId: 456,
	},
});

const { data: userData } = await callApi("https://api.example.com/users/:userId/posts/:postId", {
	params: [123, 456],
});

The resolved URL for both cases will be: "https://api.example.com/users/123/posts/456"

Parameter values are URL-encoded before being inserted. . and .. are rejected because they are reserved path segments.

Query Parameters

Include query parameters in the URL using the query option:

import { callApi } from "@zayne-labs/callapi";

const { data } = await callApi("https://api.example.com/users/123/posts", {
	query: {
		page: 1,
		limit: 10,
		sort: "latest",
		tag: ["typescript", "fetch"],
		filter: { published: true },
	},
});

Arrays become repeated keys and objects are JSON-stringified.

Top-level nullish values are omitted. URLSearchParams is also accepted. query replaces matching keys already in the URL.

Method Prefixes

CallApi provides a convenient way to specify HTTP methods directly in the URL using the @method/ prefix. This allows you to:

• Write more concise API calls by embedding the HTTP method in the URL
• Make your code more readable by keeping the HTTP method close to the endpoint

Usage

import { callApi } from "@zayne-labs/callapi";

// Using method prefix
const result = await callApi("@delete/users/123");

// Equivalent to:
const result2 = await callApi("users/123", {
	method: "DELETE",
});

How It Works

When you prefix a URL with @method/ (e.g., @get/users):

1. The method (e.g., get, post, put, etc.) is extracted from the URL
2. The extracted method is automatically set as the request method
3. The remaining part of the URL is used as the endpoint

Supported Methods

CallApi supports the following HTTP methods via URL prefixes:

• @get/ → GET requests
• @post/ → POST requests
• @put/ → PUT requests
• @delete/ → DELETE requests
• @patch/ → PATCH requests

Any other method prefix (like @head/, @options/, @trace/) will be ignored and the URL will fall back to the default GET method.

Types