accept-json v1.2.2

accept-json

Basic client for HTTP JSON APIs. Not a replacement for the very popular request and got packages.

The client can send request data as query parameters, JSON body, URL encoded body or plain text body, and expects responses to be returned as non compressed JSON body.

Overview

const apiClient = require('accept-json');

const client = apiClient('http://localhost:8080/basepath');

client.get('/path', (error, response) => {
  // process response
});

All the request methods can either be invoked with callbacks (as in the example above) or return promises:

client.get('/path').then(processResponse);

async function makeRequest() {
  let response = await client.get('/path');
}

Once instantiated, the client can be used for multiple subsequent requests:

async function makeRequest() {
  let response = await client.get('/path', {
    query: { p: 10, q: 20 }
  });
  let otherResponse = await client.post('/otherPath', {
    json: { a: 1, b: 'Hello World' }
  });
}

Options are available to configure the client and the individual requests with details such as special header fields, authentication info, request timeouts:

const client = apiClient('http://localhost:8080/basepath', {
  keepAliveMsec: 3000,
  headers: { 'x-protocol-version': '1.0' }
});

const options = {
  token: 'RHVtbXkgQmVhcmVyIFRva2Vu',
  query: { db: 'myDB', limit: 20 }
};

client.get('/path', options).then(processResponse);

Installation

npm install accept-json --save

Usage

The API client is instantiated as follows:

const apiClient = require('accept-json');

const client = apiClient(baseUrl, options);

baseUrl must be a valid URL string, starting with http:// or https://.

If present, options must be an object with following properties:

Once the API client has been instantiated, requests are made through the following methods:

client.post(path, options)

Initiates a POST request to the server. pathspecifies the request path (relative to the baseUrl configured for the client). Must be a string starting with /.

If present, callback must be a function that expects (error, result) as input parameters. Otherwise, if callback is not present, then client.post() returns a promise to resolve result or to catch error.

If present, options must be an object with the following properties:

The result value is an object defined as follows:

client.get(path, options)

Same as client.post() above, but for GET requests.

client.put(path, options)

Same as client.post() above, but for PUT requests.

client.patch(path, options)

Same as client.post() above, but for PATCH requests.

client.delete(path, options)

Same as client.post() above, but for DELETE requests.

client.options(path, options)

Same as client.post() above, but for OPTIONS requests.

client.head(path, options)

Same as client.post() above, but for HEAD requests.

client.destroy()

In general there is no need to destroy a client. However, if a client that was configured to keep persistent connection to the server is not needed any longer, it is a good idea to destroy it so that the corresponding socket(s) are freed up.