micro-rq logomicro-rq

Documentation

Headers

Configure API headers, endpoint headers, merge order, and header-related request behavior.

Request configuration

Headers

micro-rq has three places for headers: API-level headers, endpoint-level headers, and authHeader.

Use API-level headers for values shared by many requests. Use endpoint-level headers when the value depends on endpoint variables. Use authHeader only for turning an access token into auth headers.

API headers
app version, locale, tenant, client name.
Endpoint headers
request ID, idempotency key, file metadata, feature-specific headers.
Auth headers
access token headers from authHeader.

Key points

  • Header values can be static or computed at request time.
TypeScript
1export const api = createMicroApi({2  name: "main",3  baseUrl: "/api",4  headers: () => ({5    "x-client": "web",6    "accept-language": localStorage.getItem("locale") ?? "en",7  }),8  tokenProvider,9  authHeader: (token) => ({10    Authorization: `Bearer ${token}`,11  }),12});

Header merge order

Headers are merged in one predictable order.

Later headers override earlier headers with the same name. This lets endpoint headers override broad client headers, and auth headers override both when needed.

First
API-level headers from createMicroApi.
Second
endpoint-level headers mapper.
Third
authHeader when an access token exists.

Key points

  • Fetch receives a standard Headers object.
TypeScript
1const api = createMicroApi({2  name: "main",3  baseUrl: "/api",4  headers: {5    "x-source": "client",6  },7  authHeader: (token) => ({8    Authorization: `Bearer ${token}`,9  }),10});11 12const reports = api.resource("reports", {13  export: api.post<ExportResult, { reportId: string; requestId: string }>(14    ({ reportId }) => `/reports/${reportId}/export`,15    {16      headers: ({ requestId }) => ({17        "x-request-id": requestId,18      }),19    },20  ),21});

Endpoint headers

Endpoint headers are useful when header values depend on variables passed to that endpoint call.

Keep endpoint-specific headers near the endpoint definition instead of repeating them inside components.

Return any valid `HeadersInit`
object, array tuples, or Headers.

Key points

  • Use for x-request-id, idempotency-key, tenant overrides, or file metadata.
  • Endpoint headers are merged with API and auth headers automatically.
TypeScript
1type CreatePaymentInput = {2  amount: number;3  idempotencyKey: string;4};5 6export const payments = api.resource("payments", {7  create: api.post<Payment, CreatePaymentInput>("/payments", {8    body: ({ amount }) => ({ amount }),9    headers: ({ idempotencyKey }) => ({10      "idempotency-key": idempotencyKey,11    }),12  }),13});