rest.js HTTP Client

Common errors

• TypeError: rest(...).then is not a function

  cause Attempting to use rest.js v2.0.0 or later in an environment that does not natively support ES6 Promises, or where a global Promise object is not available.
  fix Ensure that a global ES6 `Promise` object is available. If targeting older environments, include a `Promise` polyfill (e.g., from `when.js` or `core-js`) before `rest.js` is loaded.

• ReferenceError: require is not defined

  cause Trying to import `rest.js` (a CommonJS module) using `require()` syntax within an ES Module (ESM) context in Node.js or a browser environment without proper transpilation or bundling configuration.
  fix For Node.js ESM projects, ensure compatibility layer or use dynamic `import('rest')`. For browser, use a bundler like Webpack/Rollup that handles CJS modules. Or, switch your file to CommonJS if possible.

• Error: Cannot find module 'rest/interceptor/entity'

  cause Attempting to import or use the `rest/interceptor/entity` interceptor, which has been deprecated and effectively removed from active use.
  fix Remove the import for `rest/interceptor/entity` and discontinue its use. Access the parsed response entity directly via `response.entity()` instead.

• TypeError: client.chain is not a function

  cause Calling `client.chain()` to compose interceptors when using a version of `rest.js` where this method has been deprecated.
  fix Update all instances of `client.chain()` to `client.wrap()` which is the preferred method for interceptor composition.

Warnings

• breaking Version 2.0.0 removed the hard dependency on `when.js` and now relies solely on the native ES6 Promise API. Users who relied on `when.js` specific features or polyfills must ensure their environment provides a global `Promise` or use a dedicated polyfill.
  Fix: Ensure your environment supports native ES6 Promises, or include a polyfill like `when.js`'s ES6 shim before loading rest.js. Update promise handling logic to conform to ES6 Promise standards.
• breaking AMD (Asynchronous Module Definition) module support was completely removed in version 2.0.0. This affects users of AMD loaders like RequireJS or curl.js, who can no longer directly load rest.js as an AMD module.
  Fix: Migrate to CommonJS (Node.js) or bundle for browser environments using tools like Browserify or Webpack. For curl.js users, the `cjsm11` loader might offer a workaround.
• breaking The automatic path token parameter replacement feature was moved from core clients into the `rest/interceptor/params` interceptor, which itself is deprecated. This behavior is no longer applied automatically.
  Fix: Manually apply parameter replacement before making requests, or consider using other interceptors/utilities for URI templating if needed. The `params` interceptor can still be used but is considered deprecated.
• deprecated The `rest/interceptor/entity` interceptor was deprecated. Its functionality is now available directly on the response object via `response.entity()`.
  Fix: Remove the `rest/interceptor/entity` interceptor from your client chain and access the parsed entity directly using `response.entity()` after a request completes.
• deprecated The `client.chain()` method for composing interceptors was deprecated in favor of `client.wrap()`.
  Fix: Replace all calls to `client.chain()` with `client.wrap()` when configuring interceptors.
• gotcha For browser consumers, the recommended main module path changed from `rest/rest` to `rest/browser` to allow bundlers like Browserify and Webpack to better optimize the build.
  Fix: Update your import paths in browser-side code from `require('rest/rest')` to `require('rest/browser')`.

Install

• npm install rest npm
• yarn add rest yarn
• pnpm add rest pnpm

Imports

• rest
  wrong:

  import rest from 'rest';

  correct:

  const rest = require('rest');

  Primary usage is CommonJS. ESM import syntax is not directly supported without a CJS-to-ESM wrapper or bundler configuration.
• mime
  wrong:

  import { mime } from 'rest/interceptor/mime';

  correct:

  const mime = require('rest/interceptor/mime');

  Interceptors are typically imported from specific paths using CommonJS require.
• errorCode
  wrong:

  import errorCode from 'rest/interceptor/errorCode';

  correct:

  const errorCode = require('rest/interceptor/errorCode');

  Similar to other interceptors, use CommonJS require for direct import.

Quickstart

This quickstart demonstrates how to create an advanced `rest.js` client by composing multiple interceptors, including `pathPrefix` for base URL, `defaultRequest` for adding common headers, `mime` for automatic JSON parsing, and `errorCode` for robust error handling. It shows both GET and POST requests, using `process.env` for API key management.

const rest = require('rest');
const mime = require('rest/interceptor/mime');
const errorCode = require('rest/interceptor/errorCode');
const defaultRequest = require('rest/interceptor/defaultRequest');
const pathPrefix = require('rest/interceptor/pathPrefix');

// Assume a base URL and an API key for a hypothetical service
const API_BASE_URL = 'https://api.example.com';
const API_KEY = process.env.MY_API_KEY ?? 'your-secret-api-key'; // Use process.env for robustness

// Configure a client with common interceptors
// pathPrefix to handle base URL
// defaultRequest to add common headers like Authorization
// mime to automatically parse JSON responses
// errorCode to handle HTTP error statuses gracefully
const client = rest
    .wrap(pathPrefix, { prefix: API_BASE_URL })
    .wrap(defaultRequest, {
        headers: {
            'Authorization': `Bearer ${API_KEY}`,
            'Accept': 'application/json'
        }
    })
    .wrap(mime, { mime: 'application/json' })
    .wrap(errorCode, { code: 400 }); // Treat 400 and above as errors

// Make a request to fetch user data
client({ path: '/users/123' }).then(
    function(response) {
        console.log('User data:', response.entity);
        console.log('Status:', response.status.code);
    },
    function(error) {
        console.error('Request failed:', error.entity || error.message);
        console.error('Error status:', error.status && error.status.code);
    }
);

// Example of a POST request
client({
    path: '/users',
    method: 'POST',
    entity: { name: 'John Doe', email: 'john.doe@example.com' }
}).then(
    function(response) {
        console.log('New user created:', response.entity);
    },
    function(error) {
        console.error('Failed to create user:', error.entity || error.message);
    }
);