API Server

API-Server

The API-Server is responsible for collecting data from public and private chains, generating statistics from the data and distributing the data to the clients.

API

Access data

You will always receive a list of objects with the format (example):

[
  {
    "_id": "5a3137b183ad4b001eca0f4d",
    "avgBlocktime": 15.0965,
    "avgHashrate": 19563481,
    "numberOfMiners": 57116,
    "numberOfWorkers": 159521,
    "timeToNextEpoch": 212317.176,
    "timeStamp": 1513174961089,
    "chain": "ethereum",
    "__v": 0
  }
]

Access chain data

The accessibility parameter has to be set to 'public' or 'private'.

http://localhost:2020/api/:accessibility/:chainName

To access the last n items:

http://localhost:2020/api/:accessibility/:chainName?numberOfItems=n

Or to access items in a specific timeframe x-y

(the time has to be formatted as UTC standard e.g.: 2017-12-19T11:00:06.000Z):

http://localhost:2020/api/:accessibility/:chainName?startTime=x&endTime=y

Or to access a specific amount of items in a specific timeframe x-y

(the time has to be formatted as UTC standard e.g.: 2017-12-19T11:00:06.000Z):

http://localhost:2020/api/:accessibility/:chainName?startTime=x&endTime=y&numberOfItems=z

The maximum number of items you can access is fixed to 10.000.

Access logs

To print out the logs of the server you can simply access them via this link:

http://localhost:2020/log?startTime=v&endTime=w&numberOfItems=x&logLevel=y

The time has to be formatted as UTC standard. Currently the standard number of log entries that will be returned is set to 1000. You can increase this number with the numberOfItems parameter. The logLevel parameter can be set to:

• trace
• debug
• info
• warn
• error
• fatal

Send data

Create a connection to

ws://localhost:3030/

and send the data as JSON-Strings with the following format (example):

{
  “hostId”: “5a3137b183ad4b001eca0f4d”,
  “isMining”: 1,
  “gasPrice”: 18000000,
  “hashrate”: 42,
  “avgBlocktime”: 20,
  “avgDifficulty”: 78
}

Docker architecture

We want to run the API-server operating system independent. To achieve this we decided on a docker based architecture. The API-server and the DMBS run in separate docker containers connected via a docker network.

Collect data

Our server collects data that is relevant for our statistics by requesting it from online providers and from the private block chain we set up.

Public chain data

To gather public chain data, the API-Server accesses the provided API of serveral websites, that offer free statistics of the most important and relevant block chains. We minimize the traffic to those websites by caching their results. This will not influence the result, because the values do not change often.

Private chain data

To gather information about our private block chain, the API-Server provides an interface for all docker nodes that are involved in the current block chain setting. The nodes can push their information on the server via a socket and the server selects and stores relevant data.

Make data accessable

Our API-Server provides an interface via a http-express server. It responds to data requests with a JSON-string.

Store gathered information

Storing the data we receive allows us to provide further statistics and detect fluctuations and anomalies over a long time analysis.

Database Management System

Our storage technology has to handle serveral different analytical tasks and a huge amount of new data that has to be collected simultaneously. So we thought about choosing a row based database management system to minimize the time to write new data. Another major reason is the format of the data we are gathering. We chose JSON-objects as our main data format for all data transfers - the information retrieved by the docker nodes is pushed into the server as JSON-objects. By choosing a NoSQL DBMS we could easily adapt our database layout to these, so there is little to no need parsing the nodes' information. But a SQL database should work as well. We selected MongoDB as our DBMS.

Security

To secure the database we enabled authentication. So every time a client wants to connect to the database he has to authenticate himself with a username and a password against the admin database running on MongoDB. The database has three users:

• root
• admin
• chainboarddbuser

The root user will be created within the entrypoint script for the MongoDB-Docker using environment variables provided by the .env file. Admin and chainboarddbuser will be created by the createDbUser script. Chainboarddbuser will only have read and write rights for the chainboarddb database. The script uses the same environment variables to authenticate as root. After the creation of the users we can start the API-server. The API-server gathers the login credentials from the .env file and authenticates itself as chainboarddbuser. After the procedure we delete the .env file and the database is secured.

Filter the amount of incoming data

Another approach to store the data correctly with good performance is to provide two seperate database tables. The whole traffic will be stored in one of the tables for a certain amount of time. After the time is up, the traffic will be redirected into the second table and the first table can be aggregated and the prepared data will be stored in the main table. Then we drop the first table and create a new one to which the traffic can be redirected after the time is up.

Provide the data to the Frontend

The Frontend can use our API-calls to access the data. The number of items responding to the Frontend is limited to 10.000.

Deployment on the BPT-Server

To deploy our server on the BPT-Server we secured our database by enabling authentication. The Server is now accessible via the BPT-Server.

Testing

Testing of the API Server is done via https://mochajs.org and https://istanbul.js.org/ is used to generate coverage statistics. The tests themselves don't have to be called explicitly, all methods in the test folder are executed recursively.