Node.js REST Client

3.1.1 · active · verified Sun Apr 19

node-rest-client is a versatile Node.js library for interacting with RESTful APIs, designed to simplify HTTP/HTTPS requests. It offers features such as transparent handling of HTTP/HTTPS connections, basic authentication, and support for common HTTP methods (GET, POST, PUT, DELETE, PATCH), with the ability to define custom methods. A key differentiator is its capability to register remote API operations as reusable client methods, streamlining code and promoting reuse. The library also manages dynamic path and query parameters, request headers, provides improved error handling, supports compressed responses (gzip, deflate), follows redirects (via `follow-redirects`), and allows for custom request serializers and response parsers (with JSON and XML included by default). The current stable version is 3.1.1. Release cadence is not strictly scheduled, but the project shows active development with recent major and minor updates.

Common errors

```
TypeError: client.post is not a function
```
cause Attempting to call `post`, `put`, or `patch` methods without providing the necessary `args` object.

fix Ensure the second argument to `client.post`, `client.put`, or `client.patch` is always an `args` object, even if empty, before the callback function.
```
Error: Response data is not parsed correctly. Expected JSON but received raw string/buffer.
```
cause The default response parsers (JSON, XML) do not match the `Content-Type` header of the API response, or the response contains malformed data.

fix Verify the `Content-Type` header sent by the API. If it's a custom type or not correctly handled, configure custom response parsers using `client.registerParser()` or `new Client({ mimetypes: { /* ... */ } })`.
```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use `require('node-rest-client')` in a Node.js environment configured for ECMAScript Modules (ESM) (e.g., `"type": "module"` in `package.json`).

fix For ESM projects, use dynamic `import('node-rest-client')` and then access the `Client` class, e.g., `const { Client } = await import('node-rest-client');`. Alternatively, ensure your file is treated as CommonJS (e.g., `.cjs` extension or no `"type": "module"` in `package.json`).

Warnings

breaking With the introduction of v3.0.0, the library prefixed all internal methods with a `$` to prevent potential name clashes with custom registered methods. If you were directly accessing or overriding internal methods in versions prior to v3, your code will break.
Fix: Review your code for any direct calls to non-public `node-rest-client` methods. If such calls exist, either refactor to use documented public APIs or adjust to the new `$` prefixed names, noting this is an internal implementation detail and subject to change.
gotcha When performing POST, PUT, or PATCH requests, the 'Content-Type' header must be explicitly set in the `args.headers` parameter. Failing to do so will result in the request body not being properly sent or parsed by the remote API.
Fix: Always include `headers: { 'Content-Type': 'application/json' }` (or appropriate type) in the `args` object for methods sending a request body (POST, PUT, PATCH).
gotcha For responses other than default JSON or XML, or if a different encoding is used, you may need to configure custom response parsers or specify `mimetypes` in the `Client` options. Otherwise, the `data` callback parameter might contain unparsed raw data or incorrect types.
Fix: If your API returns non-standard content types or requires specific parsing, add custom parsers to the client configuration. For example, `new Client({ mimetypes: { json: ['application/json', 'application/json;charset=utf-8'] } })` to explicitly define how content types are handled.

Install

npm install node-rest-client npm
yarn add node-rest-client yarn
pnpm add node-rest-client pnpm

Imports

Client
wrong:
```
import { Client } from 'node-rest-client';
```
correct:
```
const Client = require('node-rest-client').Client;
```
The library primarily uses CommonJS `require` syntax as demonstrated in its documentation. Direct ESM `import` statements may require specific Node.js configuration or dynamic imports for interoperability.
Client (full module)
wrong:
```
import nodeRestClient from 'node-rest-client';
```
correct:
```
const nodeRestClient = require('node-rest-client');
const Client = nodeRestClient.Client;
```
The `Client` class is a named export from the CommonJS module. Access it via the `.Client` property of the `require`'d module object.

Custom Method Registration

wrong:

client.myMethod(function(data, response){ /* ... */ });

correct:

client.registerMethod('myMethod', 'http://example.com/api', 'GET');
client.methods.myMethod(function(data, response){ /* ... */ });

Registered methods are accessed through the `client.methods` object, not directly on the client instance.

Quickstart

This quickstart demonstrates how to install `node-rest-client` and perform both a simple HTTP GET request and an HTTP POST request with JSON data and headers to a public API.

const Client = require('node-rest-client').Client;

const client = new Client();

// Example: Simple HTTP GET request
client.get("https://jsonplaceholder.typicode.com/posts/1", function (data, response) {
	// parsed response body as js object
	console.log('GET Response Data:', data);
	// raw response
	console.log('GET Response Status:', response.statusCode);
});

// Example: HTTP POST request with JSON data and headers
const args = {
	data: { title: 'foo', body: 'bar', userId: 1 },
	headers: { "Content-Type": "application/json" }
};

client.post("https://jsonplaceholder.typicode.com/posts", args, function (data, response) {
	console.log('POST Response Data:', data);
	console.log('POST Response Status:', response.statusCode);
});

view raw JSON →