master

Usage

To use this library in your JavaScript code, it first needs to be required:

var httpClient = require('/lib/http-client');

To make an HTTP or HTTPS request just call the request function with the desired parameters.

var response = httpClient.request({
    url: 'http://somehost/my/service', (1)
    method: 'POST',                    (2)
    headers: {
        'Cache-Control': 'no-cache'    (3)
    },
    connectionTimeout: 20000,          (4)
    readTimeout: 5000,                 (5)
    body: '{"id": 123}',               (6)
    contentType: 'application/json'    (7)
});

1	The target URL for the request. Should be a valid http:// or https:// URL.
2	The HTTP method, if omitted the GET method will be used.
3	Optional request headers can be specified.
4	Maximum time (ms) to wait for the connection to be established.
5	Maximum time (ms) to wait for the server to send back data.
6	The body of the HTTP request.
7	The content type of the request.

The function will return an object with the properties of the HTTP response:

response = {
    'status': 200,               (1)
    'message': 'OK',             (2)
    'body': 'Response contents', (3)
    'contentType': 'text/plain', (4)
    'headers': {
        'Content-Length': '17',  (5)
        'content-type': 'text/plain'
    }
};

1	HTTP status code.
2	HTTP status message.
3	Contents of the body if it’s text. For binary contents see `bodyStream` property below.
4	Content type of the response.
5	Response HTTP headers.

API

The following function is defined in this library.

`request(options)`

Sends an HTTP request and returns the response received from the remote server. The request is made synchronously, that means the execution will block until the response is received.

Parameters

The request function takes a parameter object with options. The only mandatory option is the url.

options (object) Parameters to make the HTTP request.
- url (string) URL to which the request is sent.
- method (string) The HTTP method to use for the request (e.g. "POST", "GET", "HEAD", "PUT", "DELETE", "PATCH"). The default value is "GET".
- queryParams (object) [v2.2.0+] Query parameters to be sent with the request.
- params (object) Form parameters to be sent with the request. Will not be used if queryParams is provided.
- headers (object) HTTP headers, an object where the keys are header names and the values the header values.
- connectionTimeout (number) The timeout on establishing the connection, in milliseconds. The default value is 10000.
- readTimeout (number) The timeout on waiting to receive data, in milliseconds. The default value is 10000.
- body (string | object) Body content to send with the request, usually for POST or PUT requests. It can be of type string or stream.
- contentType (string) Content type of the request.
- followRedirects (boolean) If set to false, redirect responses (status=3xx) will not trigger a new internal request, and the function will return directly with the 3xx status. The default value true.
- multipart (object[]) Multipart form data to send with the request, an array of part objects. Each part object contains 'name', 'value', and optionally 'fileName' and 'contentType' properties. Where 'value' can be either a string or a Stream object.
- auth (object) Settings for basic authentication.
  - user (string) User name for basic authentication.
  - password (string) Password for basic authentication.
- proxy (object) Proxy settings.
  - host (string) Proxy host name or IP address to use.
  - port (number) Proxy port to use.
  - user (string) User name for proxy authentication.
  - password (string) Password for proxy authentication.
- certificates (*) Stream of PEM encoded certificates. Replaces the host platform’s certificate authorities with a custom certificate.

Returns

The function will return a response object with the following properties:

status (number) HTTP status code returned.
message (string) HTTP status message returned.
headers (object) HTTP headers of the response.
cookies (object) Array of HTTP cookies set in the response.
contentType (string) Content type of the response.
body (string) Body of the response as string. Null if the response content-type is not of type text.
bodyStream (object) Body of the response as a stream object.

Examples

`Basic Authentication`

var httpClient = require('/lib/http-client');

var response = httpClient.request({
    url: 'http://somehost/protected/service',
    method: 'GET',
    auth: {
        user: 'username',
        password: 'secret'
    }
});

`Request via Proxy`

var httpClient = require('/lib/http-client');

var response = httpClient.request({
    url: 'http://somehost/some/service',
    method: 'GET',
    proxy: {
        host: '172.16.0.42',
        port: 8080,
        user: 'admin',
        password: 'secret'
    }
});

`Multipart POST request`

var httpClient = require('/lib/http-client');

var response = httpClient.request({
    url: 'http://somehost/uploadMedia',
    method: 'POST',
    contentType: 'multipart/mixed',
    multipart: [
        {
            name: 'media',
            fileName: 'logo.png',
            contentType: 'image/png',
            value: myImageStream
        },
        {
            name: 'category',
            value: 'images'
        }
    ]
});

`Using custom certificate`

var httpClient = require('/lib/http-client');
var ioLib = require('/lib/xp/io');  // IO API library from XP
var token = app.config['token']; // Token stored in the application config file
var certificates = app.config['certificates']; // Certificate stored in the application config file

var response = httpClient.request({
    url: 'http://somehost/some/service',
    method: 'POST',
    headers: {'Authorization': 'Bearer ' + token},
    contentType: 'application/json',
    certificates: ioLib.newStream(certificates)
});

Compatibility

This library is not compatible with XP releases before version 7.0. Make sure you reference the lib as /lib/http-client and not as /lib/xp/http-client or /site/lib/xp/http-client.

HTTP Client Library

Contents