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 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:
Since version 1.0.1, the Whiteflag API has a lightweight embedded datastore, making MongoDB an optional dependency:
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 link
To run an automated test of the software, use the following command in the deployment directory:
npm test
The API uses three optional environment variables:
WFLOGLEVEL
: the logging level to be used; if set, it overrides the level set in the api.toml
configuration fileWFCONFDIR
: the directory containing the configuration files; if set, it overrides the default ./config
directoryWFPORT
: the server port to be used; if set, it overrides the port set in the api.toml
configuration fileConfigurable 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 parametersPlease 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:
wfapi
Using 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 start
The 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 validatedA 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 test
Any 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.json
The 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.