diff --git a/docs/Docs/HTTP_API_Server.md b/docs/Docs/HTTP_API_Server.md new file mode 100644 index 0000000..333a837 --- /dev/null +++ b/docs/Docs/HTTP_API_Server.md @@ -0,0 +1,47 @@ +# 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`. + +```js +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. + +```js +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"); +} +``` diff --git a/docs/Plugin API/httpserver.md b/docs/Plugin API/httpserver.md index d84b378..0df10b3 100644 --- a/docs/Plugin API/httpserver.md +++ b/docs/Plugin API/httpserver.md @@ -9,6 +9,7 @@ Add features to PostalPoint's integrated LAN HTTP API server. * [.addEndpoint(id, onCall)](#httpserver.addEndpoint) * [.getServerPort()](#httpserver.getServerPort) ⇒ number * [.getClientKey()](#httpserver.getClientKey) ⇒ string + * [.sendRequestToRemote(data, endpointID, serverAddress, serverPort)](#httpserver.sendRequestToRemote) ⇒ Promise.<Object> @@ -47,3 +48,22 @@ Get the local machine's HTTP client key it uses to authenticate with other installations of PostalPoint on the LAN. **Kind**: static method of [httpserver](#httpserver) + + +### httpserver.sendRequestToRemote(data, endpointID, serverAddress, serverPort) ⇒ Promise.<Object> +Send a HTTP request to another PostalPoint installation on the local network. + +**Kind**: static method of [httpserver](#httpserver) +**Returns**: Promise.<Object> - - The JSON reply. +**Throws**: + +- Error When there's a network or other unrecoverable error while completing the request. Error message is a human-readable description of the problem. + + +| Param | Type | Description | +| --- | --- | --- | +| data | Object | Data to encode as JSON in the request body. | +| endpointID | string | Endpoint to call. | +| serverAddress | string \| undefined | Address of the PostalPoint server. If undefined, uses the host address configured in PostalPoint's Databases settings. | +| serverPort | number \| undefined | Port of the PostalPoint server. If undefined, the default PostalPoint port number is used. | +