HTTP Client Library
Contents
HTTP Client Library
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.1.2'
}
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 ifqueryParams
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 is10000
. -
readTimeout
(number) The timeout on waiting to receive data, in milliseconds. The default value is10000
. -
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 tofalse
, redirect responses (status=3xx
) will not trigger a new internal request, and the function will return directly with the3xx
status. The default valuetrue
. -
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
.