Simplified JSON HTTP Client

Common errors

• npm WARN deprecated request@2.88.2: request has been deprecated, see https://github.com/request/request/issues/3142

  cause This warning appears because `request-json` depends on the `request` package, which is no longer maintained.
  fix While this specific warning cannot be 'fixed' within `request-json` without updating its core dependency, it signals an urgent need to migrate away from `request-json` to a modern HTTP client library for security and stability reasons.

• TypeError: request.createClient is not a function

  cause Attempting to use `new` keyword with `createClient()` or calling `createClient` before requiring `request-json`.
  fix Ensure `const request = require('request-json');` is correctly placed and `createClient()` is called directly on the imported `request` object: `const client = request.createClient('http://localhost:8888/');`.

• UnhandledPromiseRejectionWarning: Unhandled promise rejection.

  cause A promise-returning method (e.g., `client.get().then(...)`) encountered an error, but no `.catch()` handler was provided.
  fix Always chain a `.catch(err => { console.error(err); })` to any promise-returning `request-json` method to handle potential errors.

Warnings

• breaking The underlying `request` library, which `request-json` relies on, was fully deprecated on February 11, 2020. This means `request-json` is built on an unmaintained and potentially insecure foundation, lacking future updates, bug fixes, or security patches.
  Fix: Migrate to a modern, actively maintained HTTP client like `axios`, `node-fetch`, or `undici`. If migrating from `request`, consider `got` as a direct successor.
• deprecated The `newClient()` method is deprecated. While still functional, it will emit a deprecation warning.
  Fix: Always use `request.createClient()` instead of `new request.newClient()`.
• gotcha Error handling typically relies on Node.js-style callbacks (`(err, res, body) => {}`) where the first argument is an error. For promise-based calls, `.catch()` should be used.
  Fix: Ensure both `err` argument in callbacks and `.catch()` blocks for promises are implemented to handle network or API errors gracefully.
• gotcha The package uses CommonJS `require()` syntax exclusively. It does not provide native ES module exports, which is the standard for modern JavaScript projects.
  Fix: Continue using `require('request-json')` in CommonJS environments. For ES module environments, a wrapper or re-bundling might be necessary, or ideally, migrate to a native ESM-compatible HTTP client.
• gotcha File upload methods (`sendFile`) have specific key naming conventions (`'file'` for single files, `'file0', 'file1', ...` for arrays) which might not align with all API expectations, requiring server-side adaptation or careful client-side data preparation.
  Fix: Verify the expected key names for file uploads on your target API and adapt the `request-json` usage or implement custom file handling if necessary.

Install

• npm install request-json npm
• yarn add request-json yarn
• pnpm add request-json pnpm

Imports

• request
  wrong:

  import request from 'request-json'

  correct:

  const request = require('request-json');

  This package is CommonJS-only and does not provide ES module exports. Direct import of the module is usually followed by calling `createClient()`.
• createClient
  wrong:

  const client = new request.newClient('http://localhost:8888/');

  correct:

  const client = request.createClient('http://localhost:8888/');

  The `newClient()` method is deprecated in favor of `createClient()` and will emit a warning, although it remains functional.
• post

  client.post('posts/', data, (err, res, body) => { /* ... */ });

  Most client methods (`get`, `post`, `put`, `del`, `patch`, `sendFile`, `saveFile`) primarily accept a callback, but also return a Promise for `.then().catch()` usage.

Quickstart

This quickstart demonstrates how to initialize the request-json client and perform various HTTP methods (POST, GET, PUT, DELETE, PATCH) to a mock API endpoint, including basic authentication and custom headers. It showcases both callback-based and promise-based approaches.

const request = require('request-json');
const client = request.createClient('http://localhost:8888/');

console.log('--- Simulating API calls to http://localhost:8888/ ---');

// POST request
const postData = {
  title: 'my title',
  content: 'my content'
};
client.post('posts/', postData, function(err, res, body) {
  if (err) return console.error('POST Error:', err);
  console.log(`POST /posts/ Status: ${res.statusCode}`);
  // console.log('POST Body:', body); // In a real scenario, body would contain the API's response
});

// GET request
client.get('posts/', function(err, res, body) {
  if (err) return console.error('GET Error:', err);
  console.log(`GET /posts/ Status: ${res.statusCode}`);
  // console.log('GET Body (first title):', body?.rows?.[0]?.title); // Assuming a structure, this would be undefined without a real server
});

// PUT request
const putData = {
  title: 'my new title'
};
client.put('posts/123/', putData, function(err, res, body) {
  if (err) return console.error('PUT Error:', err);
  console.log(`PUT /posts/123/ Status: ${res.statusCode}`);
});

// DELETE request
client.del('posts/123/', function(err, res, body) {
  if (err) return console.error('DEL Error:', err);
  console.log(`DEL /posts/123/ Status: ${res.statusCode}`);
});

// PATCH request with Promises
const patchData = {
  title: 'my patched title'
};
client.patch('posts/123/', patchData)
  .then(function(result) {
    console.log(`PATCH /posts/123/ Status: ${result.res.statusCode}`);
    // console.log('PATCH Body:', result.body);
  })
  .catch(err => {
    console.error('PATCH Error:', err);
  });

// Basic Authentication example
client.setBasicAuth('john', 'secret');
client.get('private/posts/', function(err, res, body) {
  if (err) return console.error('Auth GET Error:', err);
  console.log(`Authenticated GET /private/posts/ Status: ${res.statusCode}`);
});

// Headers manipulation
client.headers['X-Custom-Header'] = 'MyValue';
console.log('Client configured with X-Custom-Header.');