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
responseCodeDescription
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 methodThe HTTP method to be used. Supported values are "GET", "PUT", "POST", "DELETE", "HEAD", "OPTIONS", "TRACE", "PROPFIND", "MKCOL", "COPY", "MOVE", "LOCK", "UNLOCK", "PROPPATCH", "PATCH".
string uriAn absolute http: or https: URI.

Return value

HttpClientRequestAn 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 timeoutMsThe desired timeout in milliseconds. 0 means that no timeout shall be used.

Return value

HttpClientA 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

HttpClientRequestA 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 fieldName of the header field.
string valueValue of the header field.

Return value

HttpClientRequestA 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 valueAn Internet Media Type value.

Return value

HttpClientRequestA 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 valueThe content length in bytes.

Return value

HttpClientRequestA 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 bufferSizeThe maxiumum number of bytes that shall be received per callback.

Return value

HttpClientRequestA 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

HttpClientRequestA 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

HttpClientRequestA 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 dataThe data to be sent.
bool lastfalse 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

HttpClientRequestA 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

HttpClientRequestA 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

HttpClientRequestA 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

integerIf the response header has been received already: The HTTP status code of the response.
undefinedIf the response header has not been received yet.
var code = req.responseCode();
responseCodeDescription
Returns the HTTP response status code and reason phrase (e.g. "404 Not Found").
Optional. Can be called after the request is completed and the response has been received.

Return value

stringIf the response header has been received already: The HTTP status code and reason phrase of the response.
undefinedIf the response header has not been received yet.
var description = req.responseCodeDescription();
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 fieldThe 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");
close
Can be used to abort the request at any time.

Return value

HttpClientRequestA 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");
    });