Docs Developer Site
Http Client Library
arrow-down

HTTP Client Library

Contents

HTTP Client Library

xp 7.+ blue

Easily access remote web API’s and data sources over HTTP using this library.

To start using this library, add the following into your build.gradle file:

dependencies {
  include 'com.enonic.lib:lib-http-client:2.0.0
}

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"). The default value is "GET".

    • params (object) Query or form parameters to be sent with the request.

    • 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.

    • 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.

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'
        }
    ]
});

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.

Contents