{"id":15806,"library":"rest","title":"rest.js HTTP Client","description":"rest.js is an HTTP client library designed for both browser and Node.js environments, emphasizing extensibility through its interceptor-based architecture. It provides core functionality for making HTTP requests and normalizing request/response objects, with advanced features like MIME type conversion, error handling, and hypermedia API traversal implemented as composable interceptors. The current stable version is 2.0.0, which notably moved from a hard dependency on `when.js` to native ES6 Promises and completely dropped AMD module support. Releases historically occurred somewhat frequently for major feature additions in 1.x, with 2.0.0 being a significant breaking change. It allows developers to configure tailored HTTP clients by wrapping a basic client with only the necessary features, promoting a lightweight and modular approach to client-side HTTP interactions, differentiating it from monolithic HTTP libraries.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/cujojs/rest","tags":["javascript","rest","http","client","rest-template","spring","cujojs"],"install":[{"cmd":"npm install rest","lang":"bash","label":"npm"},{"cmd":"yarn add rest","lang":"bash","label":"yarn"},{"cmd":"pnpm add rest","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary usage is CommonJS. ESM import syntax is not directly supported without a CJS-to-ESM wrapper or bundler configuration.","wrong":"import rest from 'rest';","symbol":"rest","correct":"const rest = require('rest');"},{"note":"Interceptors are typically imported from specific paths using CommonJS require.","wrong":"import { mime } from 'rest/interceptor/mime';","symbol":"mime","correct":"const mime = require('rest/interceptor/mime');"},{"note":"Similar to other interceptors, use CommonJS require for direct import.","wrong":"import errorCode from 'rest/interceptor/errorCode';","symbol":"errorCode","correct":"const errorCode = require('rest/interceptor/errorCode');"}],"quickstart":{"code":"const rest = require('rest');\nconst mime = require('rest/interceptor/mime');\nconst errorCode = require('rest/interceptor/errorCode');\nconst defaultRequest = require('rest/interceptor/defaultRequest');\nconst pathPrefix = require('rest/interceptor/pathPrefix');\n\n// Assume a base URL and an API key for a hypothetical service\nconst API_BASE_URL = 'https://api.example.com';\nconst API_KEY = process.env.MY_API_KEY ?? 'your-secret-api-key'; // Use process.env for robustness\n\n// Configure a client with common interceptors\n// pathPrefix to handle base URL\n// defaultRequest to add common headers like Authorization\n// mime to automatically parse JSON responses\n// errorCode to handle HTTP error statuses gracefully\nconst client = rest\n    .wrap(pathPrefix, { prefix: API_BASE_URL })\n    .wrap(defaultRequest, {\n        headers: {\n            'Authorization': `Bearer ${API_KEY}`,\n            'Accept': 'application/json'\n        }\n    })\n    .wrap(mime, { mime: 'application/json' })\n    .wrap(errorCode, { code: 400 }); // Treat 400 and above as errors\n\n// Make a request to fetch user data\nclient({ path: '/users/123' }).then(\n    function(response) {\n        console.log('User data:', response.entity);\n        console.log('Status:', response.status.code);\n    },\n    function(error) {\n        console.error('Request failed:', error.entity || error.message);\n        console.error('Error status:', error.status && error.status.code);\n    }\n);\n\n// Example of a POST request\nclient({\n    path: '/users',\n    method: 'POST',\n    entity: { name: 'John Doe', email: 'john.doe@example.com' }\n}).then(\n    function(response) {\n        console.log('New user created:', response.entity);\n    },\n    function(error) {\n        console.error('Failed to create user:', error.entity || error.message);\n    }\n);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove the `rest/interceptor/entity` interceptor from your client chain and access the parsed entity directly using `response.entity()` after a request completes.","message":"The `rest/interceptor/entity` interceptor was deprecated. Its functionality is now available directly on the response object via `response.entity()`.","severity":"deprecated","affected_versions":">=1.2.0"},{"fix":"Replace all calls to `client.chain()` with `client.wrap()` when configuring interceptors.","message":"The `client.chain()` method for composing interceptors was deprecated in favor of `client.wrap()`.","severity":"deprecated","affected_versions":">=1.1.0"},{"fix":"Update your import paths in browser-side code from `require('rest/rest')` to `require('rest/browser')`.","message":"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.","severity":"gotcha","affected_versions":">=1.2.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: rest(...).then is not a function"},{"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.","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.","error":"ReferenceError: require is not defined"},{"fix":"Remove the import for `rest/interceptor/entity` and discontinue its use. Access the parsed response entity directly via `response.entity()` instead.","cause":"Attempting to import or use the `rest/interceptor/entity` interceptor, which has been deprecated and effectively removed from active use.","error":"Error: Cannot find module 'rest/interceptor/entity'"},{"fix":"Update all instances of `client.chain()` to `client.wrap()` which is the preferred method for interceptor composition.","cause":"Calling `client.chain()` to compose interceptors when using a version of `rest.js` where this method has been deprecated.","error":"TypeError: client.chain is not a function"}],"ecosystem":"npm"}