@backpack/rest-client️ 🌍

A pre-configured REST client built on top of Wretch, enhanced with additional middleware for extended functionality.

Installing

First, ensure you have set up Nexus as private registry needed to use Backpack.

Then, install the package using npm:

npm install @backpack/rest-client

Example usage

Wretch is basically a thin wrapper around the Fetch API:

import { createRestClient } from "@backpack/rest-client";

const books = await createRestClient({ baseUrl: "https://my-book-store.com" })
  .url("/api/v1/books")
  .get()
  .json();

You can check out its documentation to learn more.

API reference

createRestClient()

Creates a Wretch instance, pre-configured with:

• QueryStringAddon: easily pass a query string as a key-value record;
• AbortAddon: adds support for cancellations and timeouts;
• ApiManagementAddon: a custom addon to add an API Management subscription keys;
• UserAgentAddon: a custom addon to easily set a user agent;
• AcceptLanguageAddon: a custom addon to easily set the accept language header;
• ZodAddon: a custom addon which adds shorthands for Zod response validation.

Example usage

import { createRestClient } from "@backpack/rest-client";

const restClient = createRestClient({
  // additional options:
  baseUrl: "https://api.bookstore.com/",
  timeoutMilliseconds: 2_000,
  apiManagementSubscriptionKey: "...",
  userAgent: "my-app/v2"
});

// additional methods: 
const result = await restClient

  // set or override subscription key:
  .apiManagementSubscriptionKey("...")

  // set or override user agent header
  // shorthand for `.headers({ "User-Agent", "..." })`:
  .userAgent("my-app")

  // set or override timeout:
  .setTimeout(2_000)

  // shorthand for `.headers({ "Accept-Language", "..." })`:
  .acceptLanguage("my-app")

  .url("/api/v1/books")
  .get()

  // shorthand for `.json().then(it => MyZodSchema.parse(it)`
  .validatedJson(MyZodSchema)

Options

Option	Type	Description
baseUrl	string	sets the base url for the REST client
timeoutMilliseconds	number	pre-configures the request timeout
apiManagementSubscriptionKey	string	pass an API management subscription key
userAgent	string	pass a user agent header

powertoolsLoggingMiddleware()

Adds logging with Powertools Logger to requests and responses:

import { createRestClient, powertoolsLoggingMiddleware } from "@backpack/rest-client";

const restClient = createRestClient()
  .middlewares([
    powertoolsLoggingMiddleware({
      logger: myLogger
      // additional options
    })
  ]);

Do you have ideas for additional middleware?

Please consider making a contribution by submitting a pull request.

Options

Option	Type	Description	Default
logger	Logger	the Powertools Logger instance
requestLogging
enabled	boolean	log request information	false
logLevel	"info" | "debug"	set the log level	"debug"
includeRequestBody	boolean	log the request body as well	false
responseLogging
enabled	boolean	log response information	false
successLogLevel	"info" | "debug"	set the log level for success responses	"debug"
error4xxLogLevel	"warn" | "error"	set the log level for 4xx responses	"warn"
error5xxLogLevel	"warn" | "error"	set the log level for 5xx responses	"error"