48 lines
2.0 KiB
Markdown
48 lines
2.0 KiB
Markdown
|
# 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");
|
||
|
|
}
|
||
|
|
```
|