sn-http-request

ServiceNow HTTP Request Client

Intended for internal ServiceNow development use only

Features

• Automatic User Token Refresh
• Asynchronous Request Queue
• Request Cancellation
• Request/response Interceptors
• Request Batching

Instructions for glide to uptake new release versions of sn-http-request:

1. Go to sn-http-request in Jenkins and cut a new release version from master with the Build with Parameters option.
2. Take a note of the new release version number.
3. Clone the sn-javascript-shared-dependencies mega bundle repo and update the package.json dependencies with the new release version noted in step 2. above from Jenkins.
4. Open a PR, add reviewers, and merge the changes to master of sn-javascript-shared-dependencies upon PR approval.
5. Go to sn-javascript-shared-dependencies in Jenkins and cut a new release version from master with the Build with Parameters option.
6. Take a note of the new release version number.
7. Assuming glide is already cloned, update the glide/glide-core-ui-components/pom.xml for artifact ID js-common-mega with the new release version number noted in step 6. above from Jenkins.
8. To be a good citizen for other developers using tectonic sync, please also update the glide/core-ui-components/npm-library-dependency-manifest.json for sn-http-request with the new release version number noted in step 2. above.
9. Open a PR, add reviewers, and merge the changes to the relevant track upon PR approval. Please check with your colleagues to determine the correct track to merge the changes to.

Installation

$   npm install sn-http-request

snHttpFactory

Import snHttpFactory to create client instances:

import  {snHttpFactory} from 'sn-http-request';

// Create an snHttp client instance
const snHttp = snHttpFactory({
    // ... options
});

Options

• xsrfToken [String] - register xsrf token for requests
• maxConcurrent [Number] - max number of requests to process at a time (Default is 2)
• batching [Boolean] - turn batching on or off for all requests for this client instance (Default is true)
• httpRequestCompressionThreshold [Number] - when this option is present the payload will be gzip compressed using fflate when the serialized payload length exceeds this value.
• httpRequestCompressionLevel [Number] - The level of compression to use, ranging from 0-9. 0 will store the data without compression. 1 is fastest but compresses the worst, 9 is slowest but compresses the best. The default level is 6. (see fflate)
• httpRequestCompressionMemoryLevel [Number] - The memory level to use, ranging from 0-12. Increasing this increases speed and compression ratio at the cost of memory. The default value is automatically determined based on the size of the input data. (see fflate.

Client

Examples

POST request

snHttp.request({
        method: 'POST',
        url:    '/user/1',
        data:   {
                firstName:  'Fred',
                lastName:   'Luddy'
        }
});

GET request

snHttp.request({
        method: 'GET',
        url:    '/user/1'
}).then(function(response)  {
        conosle.log(response);
});

Methods

• snHttp.request(config)
• snHttp.get(url [,config])
• snHttp.post(url [,config])
• snHttp.put(put [,config])
• snHttp.delete(url [,config])
• snHttp.patch(url [,config])
• snHttp.head(url [,config])

Request Config

These are the available config options for making requests. Only the url is required. Requests will default to GET if method is not specified.

{
    // `url` is the server URL that will be used for the request
    url: '/user',

    // `method` is the request method to be used when making the request
    method: 'get', // default

    // `baseURL` will be prepended to `url` unless `url` is absolute.
    // It can be convenient to set `baseURL` for an instance of axios to pass relative URLs
    // to methods of that instance.
    baseURL: 'https://some-domain.com/api/',

    // `transformRequest` allows changes to the request data before it is sent to the server
    // This is only applicable for request methods 'PUT', 'POST', and 'PATCH'
    // The last function in the array must return a string or an instance of Buffer, ArrayBuffer,
    // FormData or Stream
    // You may modify the headers object.
    transformRequest: [function (data, headers) {
        // Do whatever you want to transform the data

        return data;
    }],

    // `headers` are custom headers to be sent
    headers: {'X-Requested-With': 'XMLHttpRequest'},

    // `params` are the URL parameters to be sent with the request
    // Must be a plain object or a URLSearchParams object
    params: {
        ID: 12345
    },

    // `data` is the data to be sent as the request body
    // Only applicable for request methods 'PUT', 'POST', and 'PATCH'
    // When no `transformRequest` is set, must be of one of the following types:
    // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
    // - Browser only: FormData, File, Blob
    // - Node only: Stream, Buffer
    data: {
        firstName: 'Fred'
    },

    // `timeout` specifies the number of milliseconds before the request times out.
    // If the request takes longer than `timeout`, the request will be aborted.
    timeout: 1000, // default is `0` (no timeout)

    // `withCredentials` indicates whether or not cross-site Access-Control requests
    // should be made using credentials
    withCredentials: false, // default

}

Cancellation

You can cancel a request using the client source token with the request:

const snHttp = snHttpFactory({/* ... */});

const abortController = new AbortController();

snHttp.request(url, method, {
    /* ... options */
    signal: abortController.signal
});

abortController.abort();

Request Batching

By default, the client will batch http requests unless otherwise specified during creation via snHttpFactory.

Batching can also be configured at the individual request level via the request config. For example:

snHttp.post('/users/1', {
        data:   {fName: 'Fred'},
        batch:  false //    true    by  default
});

By default, requests made within a 50ms window will be batched into a single http request.