HTTP API Server

PostalPoint runs a local HTTP server to allow communication with other devices on the LAN.

With the httpserver plugin API, plugins can add their own local API endpoints.

Valid HTTP API requests are POST requests with either a JSON request body, or an entirely empty body.

The default HTTP server settings are to bind to all addresses on port 7678. There is a basic API web client accessible on / for manual API access, for example, at http://localhost:7678/.

Security

API requests are authenticated with a "Network Connection Key". Each installation of PostalPoint maintains a user-configurable list of keys which are allowed to connect to that installation's API server.

This means that, in order for a remote client to connect to PostalPoint, it must generate a random alphanumeric ID, which must be saved in the PostalPoint settings.

Adding an API endpoint

This code adds an endpoint reachable by POST to http://[local hostname]:[port]/testendpointname.

global.apis.httpserver.addEndpoint("testendpointname", async function (request) {
    // `request` is an object parsed from the request body.
    if (request.abc == "123") {
        // A non-string `body` is converted to JSON before the HTTP reply is sent.
        return {body: {json: true, abc: 123}, httpcode: 200, contentType: "application/json"};
    }
    // A string `body` is sent to the client as-is using whatever contentType you specify.
    return {body: "abc", httpcode: 200, contentType: "text/plain"};
});

Connecting to a remote endpoint

By default, sendRequestToRemote uses the configured "Host PC", but a different hostname/IP may be specified.

This code hits the endpoint added above.

try {
    const responseObject = await global.apis.httpserver.sendRequestToRemote({abc: "123"}, "testendpointname");
    // responseObject will be {json: true, abc: 123}
    console.log(responseObject);
} catch (ex) {
    global.apis.alert(ex.message, "Request Error");
}