HttpClient

This document describes the HttpClient available in the JavaScript environment for app serivices.

Table of content

Object	HttpClient
Functions	request timeout
Object	HttpClientRequest
Functions	auth header contentType contentLength onrecv recv onsend send oncomplete onerror responseCode responseHeader close
Examples	GET request PUT request DELETE request

HttpClient

request

Creates an HttpClientRequest object. The actual request is started asynchronously. So synchronous function calls on that object are handled before the request is sent.

Parameters

string method	The HTTP method to be used. Supported values are "GET", "PUT", "POST", "DELETE", "HEAD", "OPTIONS", "TRACE", "PROPFIND", "MKCOL", "COPY", "MOVE", "LOCK", "UNLOCK", "PROPPATCH", "PATCH".
string uri	An absolute http: or https: URI.

Return value

HttpClientRequest

An object representing the request.

var req = HttpClient.request("GET", "https://www.innovaphone.com");

timeout

Sets a timeout that shall be used for HTTP requests. If the function is not called by the application, a default timeout of 60s is used. HTTP requests will be terminated if the server does not respond or sends no more data for the specified time. In that cases the onerror callback is invoked with error "HTTP_SHUTDOWN_TIMEOUT".

Parameters

string timeoutMs

The desired timeout in milliseconds. 0 means that no timeout shall be used.

Return value

HttpClient

A reference to the object itself. Useful for method chaining.

var req = HttpClient.timeout(30000);

HttpClientRequest

auth

Sets credentials that shall be used for HTTP authentication (basic, digest, ntlm), if requested by the server.
Optional. Calls must be done before the request is sent, e.g. synchronously after creating the HttpClientRequest object.

Parameters

string username
string password

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.auth("someuser","somepassword");

header

Sets a custom request header.
Optional. Calls must be done before the request is sent, e.g. synchronously after creating the HttpClientRequest object.

Parameters

string field	Name of the header field.
string value	Value of the header field.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.header("X-Token","c29tZXRva2Vu");

contentType

Sets the content type of the request body. If the function is not called, "text/plain" will be used as a default.
Optional. Calls must be done before the request is sent, e.g. synchronously after creating the HttpClientRequest object.

Parameters

string value

An Internet Media Type value.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.contentType("application/json");

contentLength

Sets the content length of the request body. If the function is not called, chunked encoding will be used.
Optional. Calls must be done before the request is sent, e.g. synchronously after creating the HttpClientRequest object.
Setting the content length requires the application to send excactly the specified number of bytes using the send function.

Parameters

uint value

The content length in bytes.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.contentLength(17);

onrecv

Sets a callback function for receiving response data. The data is received asynchronouly using flow control. So only a specified number of bytes is received at a time. After invoking the onrecv callback, the library waits for the application to process the data. To receive the next chunk of data the application must call recv.
Optional. If no callback is set, the library will silently discard the response data.

Parameters

function callback(HttpClientRequest request, Uint8Array data, bool last)	A callback that will be called when response data is received.
int bufferSize	The maxiumum number of bytes that shall be received per callback.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

var responseData = "";

req.onrecv(function(req, data, last) {
    responseData += new TextDecoder("utf-8").decode(data);
    if (!last) req.recv();
}, 1024);

recv

Tells the library to receive the next chunk of data.
Must be called after receiving the onrecv callback, if the last parameter was false.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.onrecv(function(req, data, last) {
    if (!last) req.recv();
});

onsend

Sets a callback function for sending request body data. The data is sent asynchronouly using flow control. So the library invokes the callback to notify the application that is ready to send data. Then it waits for the application to call send. Optional. If no callback is set, the library will send a request with an empty body.

Parameters

function callback(HttpClientRequest request)

A callback that will be called when the libary is ready to send data.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.onsend(function(req) {
    req.send(new TextEncoder("utf-8").encode("somedata"), true);
});

send

Tells the library to send the next chunk of data.
Must be called after receiving the onsend callback.

Parameters

Uint8Array data	The data to be sent.
bool last	false if there is more data to be sent and the application wants to receive another onsend callback. true for the last chunk of data.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.onsend(function(req) {
    req.send(new TextEncoder("utf-8").encode("somedata"), true);
});

oncomplete

Sets a callback function that is invoked when the request is completed. Optional.

Parameters

function callback(HttpClientRequest request, bool success)

A callback that will be called when the request is complete.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.oncomplete(function(req, success) {
    log("HttpRequest " + (success ? "succeeded" : "failed"));
});

onerror

Sets a callback function that is invoked when the request has been aborted. Optional. If no onerror callback is set, aborted requests will lead to an oncomplete callback with success=false instead.

Parameters

function callback(error)

A callback that will be called when the request has been aborted. The parameter error is a string representation of http_shutdown_reason_t.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.oncomplete(function(req, success) {
    log("HttpRequest complete");
})
.onerror(function(error) {
    log("HttpRequest error=" + error);
});

responseCode

Returns the HTTP response status code.
Optional. Can be called after the request is completed and the response has been received.

Return value

integer	If the response header has been received already: The HTTP status code of the response.
undefined	If the response header has not been received yet.

var code = req.responseCode();

responseHeader

Returns the value of a header field in the response.
Optional. Can be called after the request is completed and the response has been received.

Parameters

string field

The name of the header field.

Return value

array[string]

An array of strings containing the values for the specified response header. Note that a header field can occur multiple times. That is why an array is returned instead of a single string.

var arr = req.responseHeader("X-Token");

Can be used to abort the request at any time.

Return value

HttpClientRequest

A reference to the object itself. Useful for method chaining.

req.close();

Examples

GET request

In this example we get a text file in 2048 byte chunks and print the content to the log.

var text = "";

HttpClient.request("GET", "https://www.example.com/file.txt")
    .onrecv(function (req, data, last) {
        text += new TextDecoder("utf-8").decode(data);
        if (!last) req.recv();
    }, 2048)
    .oncomplete(function(req, success) {
        if (success) log("GET OK\n" + text);
        else log("GET ERROR");
    });

PUT request

In this example we put a text file with the content "sometext".

HttpClient.request("PUT", "https://www.example.com/file.txt")
    .contentType("text/plain")
    .onsend(function(req) {
        req.send(new TextEncoder("utf-8").encode("sometext"), true);
    })
    .oncomplete(function(req, success) {
        log(success ? "PUT OK" : "PUT ERROR");
    });

DELETE request

In this example we delete a text file.

HttpClient.request("DELETE", "https://www.example.com/file.txt")
    .oncomplete(function(req, success) {
        log(success ? "DELETE OK" : "DELETE ERROR");
    });