WebServer

This document describes the WebServer object in the JavaScript environment for app serivices.

Table of content

Object WebServer
Members url
Functions onurlchanged
onrequest

Object WebServerRequest
Members method
relativeUri
Functions cancel
header
onrecv
recv
onsend
send
oncomplete
sendResponse
responseHeader
responseContentType
responseFileName

Examples REST API using GET, PUT and DELETE

WebServer

url
A string containing the absolute base URL that can be used to access the web server. The app service learns the URL from the incoming websocket connection from the app object on the PBX. So it only contains a valid URL, if the "Websocket" checkmark is set on the app object and the connection is up. Otherwise url will point to localhost. Use onurlchanged to get notified when the actual URL is available after the app service is started.
onurlchanged
Registers a callback function that is invoked when the base URL of the web server has changed.

Parameters

function callback(string newUrl)Called whenever WebServer.url has changed.

Return value

WebServerA reference to the object itself. Useful for method chaining.
var baseUrl = WebServer.url;
log("url: " + baseUrl);
        
WebServer.onurlchanged(function(newUrl) {
    baseUrl = newUrl;
    log("url: " + baseUrl);
});
onrequest
Registers a relative URI on the web server and a callback function that is invoked on incoming requests on that URI.

Parameters

string relativeUriA URL relative to WebServer.url. Do not prepend "/", "./".
function callback(WebServerRequest request)The callback will be invoked on incoming HTTP requests to the given URI. If the callback is called, the application has to handle or cancel the request.

Return value

WebServerA reference to the object itself. Useful for method chaining.
WebServer.onrequest("info.json", function(req) {
    // reject request for this example
    req.cancel();
});

WebServerRequest

The WebServerRequest object passed to the application with the onrequest callback and can be used to handle incoming HTTP requests.
method
A string containing the HTTP method that was used for the request. Supported values: .
WebServer.onrequest("info.json", function(req) {
    if (req.method == "GET") {
        // handle GET
    }
    else if (req.method == "PUT") {
        // handle PUT
    }
    else if (req.method == "POST") {
        // handle POST
    }
    else if (req.method == "DELETE") {
        // handle DELETE
    }
    else {
        // should never happen
        req.cancel();
    }
});
relativeUri
A string containing the requested ressource relative to the base URL given with the onrequest function.
WebServer.onrequest("weather", function(req) {
    if (req.method == "GET") {
        if (req.relativeUri == "/temperature") {
            // ...
        }
        else if (req.relativeUri == "/humidity") {
            // ...
        }
        else if (req.relativeUri == "/wind") {
            // ...
        }
        else {
            req.cancel();
        }
    }
    else  {
        req.cancel();
    }
});
cancel
Cancels the request. The client will get back an HTTP error. The application will get no more callbacks from the object, especially there will be no oncomplete callback.

Parameters

uint responseCodeThe HTTP status code to send with the response for the canceled request. Supported values are 404, 400, 451, 411, 402, 500. If no value is given status code 404 is used.

Return value

WebServerRequestA reference to the object itself. Useful for method chaining.
WebServer.onrequest("info.json", function(req) {
    // reject request with 500 Internal Server Error
    req.cancel(500);
});
header
Returns the value of a given header field in the request.

Parameters

string fieldThe name of the header field.

Return value

stringThe value of the specified header field.
WebServer.onrequest("info.json", function(req) {
    if (req.header("X-Token") == "c29tZXRva2Vu") {
        // handle request
    }
    else {
        req.cancel();
    }
});
onrecv
Sets a callback function for receiving request 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 request data.

Parameters

function callback(WebServerRequest request, Uint8Array data)A callback that will be called when request data is received. If the request is finished it will be called with data set to null.
int bufferSizeOptional. The maxiumum number of bytes that shall be received per callback. Defaults to 16384, if not specified.

Return value

WebServerRequestA reference to the object itself. Useful for method chaining.
var requestData = "";

req.onrecv(function(req, data) {
    if (data) {
        requestData += new TextDecoder("utf-8").decode(data);
        req.recv();
    }
}, 1024);
recv
Tells the library to receive the next chunk of data.
Must be called after receiving the onrecv callback, unless data was null.

Return value

WebServerRequestA reference to the object itself. Useful for method chaining.
req.onrecv(function(req, data) {
    if (data) {
        // process data, then receive next chunk
        req.recv();
    }
});
onsend
Sets a callback function for sending response 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 response with an empty body.

Parameters

function callback(WebServerRequest request)A callback that will be called when the libary is ready to send data.

Return value

WebServerRequestA 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

WebServerRequestA 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 / response is finished. Optional.

Parameters

function callback(WebServerRequest request, bool success)A callback that will be called when the request is complete or was aborted.

Return value

WebServerRequestA reference to the object itself. Useful for method chaining.
req.oncomplete(function(req, success) {
    log("WebServerRequest " + (success ? "succeeded" : "failed"));
});
sendResponse
Tells the library that the application has successfully processed the request and sets the HTTP status code that shall be sent with the response. Before calling this function the application has to set all parameters and callbacks that are needed to create the response, like onsend, oncomplete, responseHeader, responseContentType, or responseFileName.

Parameters

uint codeOptional. The HTTP response code to be sent to the client. Defaulting to 200, if not specified. Supported values are
  • 200
  • 201
  • 204
  • 207
  • 403
  • 405
  • 409
  • 412
  • 423
  • 502
  • 507
.

Return value

WebServerRequestA reference to the object itself. Useful for method chaining.
req.sendResponse(200);
responseHeader
Sets a custom header field that shall be sent with the HTTP response.

Parameters

string fieldThe name of the header field.
string valueThe value of the header field.

Return value

WebServerRequestA reference to the object itself. Useful for method chaining.
req.header("X-Token","c29tZXRva2Vu");
responseContentType
Sets the content type for the data transmitted with the response.

Parameters

string contentType A file name extension that will be converted to an Internet Media Type value internally by the webserver. Supported values are:
  • "html"
  • "htm"
  • "css"
  • "xml"
  • "xsl"
  • "js"
  • "json"
  • "ico"
  • "bin"
  • "jar"
  • "png"
  • "gif"
  • "bmp"
  • "pdf"
  • "wav"
  • "ogg"
  • "mp3"
  • "txt"
  • "soap"
  • "svg"
  • "ttf"
  • "eot"
  • "woff"
  • "woff2"
  • "g711a"
  • "g711u"
  • "g722"
  • "g729"
  • "jpeg"
  • "mp4"
  • "webm"
  • "pem"
  • "mobileconfig"
  • "appcache"
  • "opus-nb"
  • "opus-wb"

Return value

WebServerRequestA reference to the object itself. Useful for method chaining.
req.responseContentType("json");
responseFileName
The application can set a file name for the response data. This will cause the client to handle the HTTP response as a download. Should always be used together with responseContentType

Parameters

string filenameThe filename for the download.

Return value

WebServerRequestA reference to the object itself. Useful for method chaining.
req.responseContentType("pdf").responseFileName("invoice.pdf");

Example: REST API using GET, PUT and DELETE

In this example we see how a simple REST API can be implemented. The REST API can read, store and delete an UTF-8 string value.
// the variable containing the string value
var value = null;

WebServer.onrequest("value", function(req) {
    if (req.method == "GET") {
        if (value) {
            // value exists, send it back as text/plain
            req.responseContentType("txt")
                .sendResponse()
                .onsend(function(req) {
                    req.send(new TextEncoder("utf-8").encode(value), true);
                });
        }
        else {
            // value does not exist, send 404 Not Found
            req.cancel();
        }
    }
    else if (req.method == "PUT") {
        // overwrite existing value with newValue

        var newValue = "";
        req.onrecv(function(req, data) {
            if (data) {
                newValue += (new TextDecoder("utf-8").decode(data));
                req.recv();
            }
            else {
                value = newValue;
                req.sendResponse();
            }
        });
    }
    else if (req.method == "DELETE") {
        // delete value
        value = null;
        req.sendResponse();
    }
    else {
        req.cancel();
    }
});