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:

Property	Description
token	OPTIONAL - String; token for HTTP Bearer authentication (OAuth2)
basic	OPTIONAL - String; base64 encoding of <user>:<password> (HTTP Basic authentication); alternatively, user name and password can be specified as separate strings (see next)
user	OPTIONAL - String; user name for HTTP Basic authentication; takes effect only if also password is specified
password	OPTIONAL - String; password for HTTP Basic authentication; takes effect only if also user is specified
timeout	OPTIONAL - Integer number; request timeout in milliseconds
headers	OPTIONAL - Object; headers to be added to the request; there is no need to specify the accept header or the content-type header since they are automatically generated
rejectUnauthorized	OPTIONAL - Boolean; default to true; see tls.connect() documentation for information
ca	OPTIONAL - String, array of strings, buffer, or array of buffers; default to the list of well-known CAs curated by Mozilla; see tls.createSecureContext() for information
keepAliveMsec	OPTIONAL - Integer number; when present, creates a persistent connection to the server with the specified keep alive in milliseconds
maxSockets	OPTIONAL - Integer number; maximum number of concurrent sockets to the server; takes effect only when keepAliveMsec is specified and has 1 (single socket) as default value

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

client.post(path[, options][, callback])

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:

Property	Description
query	OPTIONAL - Object; if present, a query string is generated with the specified keys and values
json	OPTIONAL - Object; if present, the json object is serialized into a JSON body and the content-type header is set to application/json
form	OPTIONAL - Object; if present, the form object is serialized into a URL-encoded body and the content-type header is set to application/x-www-form-urlencoded; form is disregarded if json is present
text	OPTIONAL - String; if present, the text string is used as request body and the content-type header is set to text/plain; text is disregarded if json or form is present
token	OPTIONAL - String; token for HTTP Bearer authentication (OAuth2); takes precedence over the token optionally specified when instantiating the client
basic	OPTIONAL - String; base64 encoding of <user>:<password> (HTTP Basic authentication); takes precedence over the basic value optionally specified when instantiating the client; alternatively, user name and password can be specified as separate strings (see next)
user	OPTIONAL - String; user name for HTTP Basic authentication; takes effect only if also password is specified, and the two values take precedence over the user / password optionally specified when instantiating the client
password	OPTIONAL - String; password for HTTP Basic authentication; takes effect only if also user is specified, and the two values take precedence over the user / password optionally specified when instantiating the client
headers	OPTIONAL - Object; headers to be added to the request; values specified here take precedence over the corresponding values optionally specified when instantiating the client; there is no need to specify the accept header or the content-type header since they are automatically generated

The result value is an object defined as follows:

Property	Description
code	Integer number; response status code
message	String; response status message
header	Object; response headers
body	Response body returned as object if the body received from the server is parsable with JSON.parse() or as string otherwise; this is intended to be robust to misbehaving servers that send plain text responses rather than JSON responses upon certain error conditions
latency	Integer number; time interval in milliseconds from the beginning of the request to the end of the response

client.get(path[, options][, callback])

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

client.put(path[, options][, callback])

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

client.patch(path[, options][, callback])

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

client.delete(path[, options][, callback])

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

client.options(path[, options][, callback])

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

client.head(path[, options][, callback])

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.