Whiteflag is a fully neutral and secure communications means based on blockchain technology. It enables near real-time communication in armed conflicts and disasters to exchange early warning and status information to create shared situational awareness.
This Whiteflag Application Programming Interface (API) is a Node.js software implementation of the API layer that provides an interface with the Whiteflag messaging network on one or more underlying blockchains. In other words, it acts as a message transceiver between one or more blockchains and one or more end-user applications. For interaction with an end-user application, two methods are used:
- the REST API is the main interface to send Whiteflag messages on the blockchain and manage blockchain accounts, authentication, encryption keys, etc.;
- a web socket is available for clients to listen for incoming Whiteflag messages from a blockchain.
The current version is based on v1-draft.6 of the Whiteflag protocol. The
supported Whiteflag protocol features are described in SCOPE.md.
Note that the Whiteflag API is a so called Minimum Viable Product (MVP). This means that it only supports the core features of the Whiteflag protocol and nothing more. As such, it serves as the reference implementation of the Whiteflag protocol, but it is not designed and tested for secure usage and performance in a production environment.
More detailed documentation of the API is available at Github Pages
This documentation is also found in the markdown files in the docs/
directory. When the API is running, the server will also provide the OpenAPI
definition at the URL root (e.g. http://localhost:5746/).
The repository structure and development guidelines for the source code are
described in CONTRIBUTING.md.
The Whiteflag API software is dedicated to the public domain
under the Creative Commons CC0-1.0 Universal Public Domain Dedication
statement. See LICENSE.md for details.
The Whiteflag API software requires third party software packages, which are not part of this distribution and may be licenced differently.
To deploy the Whiteflag API, make sure the following prerequisite software is installed:
- Node.js version 16 or higher, including NPM
Since version 1.0.1, the Whiteflag API has a lightweight embedded datastore, making MongoDB an optional dependency:
- MongoDB, currently only fullt tested with legacy verson 3.6, but higher versions seem to work as well
First, copy the repository to the deployment directory, such as
/opt/whiteflag-api. Please use a version tagged commit for a stable version.
After copying the repository, install the required Node.js modules of external software libraries and then create a global link to the package by running the following commands in the deployment directory:
npm install
npm linkTo run an automated test of the software, use the following command in the deployment directory:
npm testThe API uses three optional environment variables:
WFLOGLEVEL: the logging level to be used; if set, it overrides the level set in theapi.tomlconfiguration fileWFCONFDIR: the directory containing the configuration files; if set, it overrides the default./configdirectoryWFPORT: the server port to be used; if set, it overrides the port set in theapi.tomlconfiguration file
Configurable parameters of the API can be found in the TOML
files in the config/ directory:
api.toml: for various general API settings, such as hostname, port, etc.blockchains.toml: for blockchain specific configurationdatastores.toml: for datastore specific configurationwhiteflag.toml: for Whiteflag protocol related parameters
Please see docs/configuration.md for more details.
To start the Whitefag API server from the command line, use the wfapi
command in the deployment directory:
wfapiUsing the npm start command in the deployment directory should also work.
Alternatively, a service may be created. An example whiteflag-api.service
for linux systems using systemctl cound be found in etc/. Enable the
and start the service with:
sudo systemctl enable ./etc/whiteflag-api.service
sudo service whiteflag-api startThe detailed OpenAPI definition can be
found in static/openapi.json. The API definition is provided in human
readible format at the root endpoint by the running API; just go to
http://localhost:5746/ with a browser.
Some of the endpoint functionalities (see the API defintion for all details):
/messages: endpoint to GET an array of all messages contained in the API database/messages/send: endpoint to POST a new Whiteflag message to be transmitted on the blockchain/messages/send: endpoint to POST a new Whiteflag as if received the blockchain/messages/encode: endpoint to POST a Whiteflag message to be encoded/messages/decode: endpoint to POST a Whiteflag message to be decoded/messages/validate: endpoint to POST a Whiteflag message to be checked for valid format and reference/messages?transactionHash=<transaction hash>: endpoint to GET a specific message by its transaction hash
/blockchains: endpoint to GET the current configuration and state of all blockchains/blockchains/{blockchain}: endpoint to GET the configuration and state of the specified blockchain/blockchains/{blockchain}/accounts: endpoint to GET account details or POST a new blockchain account/blockchains/{blockchain}/accounts/{address}endpoint to PATCH or DELETE to update or remove the specified blockchain account/blockchains/{blockchain}/accounts/{address}/sign: endpoint to POST a payload to be signed as a Whiteflag authentication signature/blockchains/{blockchain}/accounts/{address}/transfer: endpoint to POST a transaction to transfer value to another account
/originators: endpoint to GET the currently known originators/originators/{address}: endpoint to GET details of the specified originator
/signature/decode: endpoint to POST a Whiteflag authentication signature to be decoded/signature/validate: endpoint to POST a Whiteflag authentication signature to be validated
A minimal set of automated tests is implemented with the Mocha test framework. To do a full test and run all the test scripts, use the following NPM command in the project root:
npm testAny REST client, such as Postman or cURL
can be used for manual testing. This is a simple example using cURL from the
command line, sending an A1 message from a file:
curl http://localhost:5746/messages/send -X POST -H "Content-Type:application/json" -d @A1.message.jsonThe API also exposes a webpage with an embedded client side socket listener
that is available on http://localhost:5746/listen (default URL) when the
API is running.
When testing on a main blockchain network, the testMessagesOnly in
the [tx] section of the whiteflag.toml configuration file should be set
to true to prevent the accidental transmission of real messages.