CopperHammer API

An extensive API for communicating with CopperHammer workers and scanners

Communication & Models

Authorization and Registration

Node sends HTTP request to /{type}/node_register with its key in the X-API-Key header. If the authorization was successful, the server will send an answer containing nodeID (conforming to UUID4) and a token (128 bits). Since now, the node is expected to connect to /{type}/node/{nodeID} via WebSocket with a token URL-parameter containing the token.

Scanner Node

POST - /scanner/node_register

Description

Registeres a Scanner node in DB to receive authentication token.

CURL

curl -X POST "http://localhost:8000/scanner/node_register" \
    -H "X-API-Key: APITOKENKEY" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data-raw "$body"

Header Parameters

• X-API-Key should respect the following schema:

{
  "type": "string"
}

• Content-Type should respect the following schema:

{
  "type": "string",
  "enum": [
    "application/json; charset=utf-8"
  ]
}

Body Parameters

• body should respect the following schema:

{
  "type": "string",
  "default": "{\"action\":\"AUTHENTICATE_REQUEST\"}"
}

WEBSOCKET - /scanner/node/nodeID

Description

Connects to Scanner Node websocket with a give nodeID and token.

JavaScript Example

const WebSocket = require("ws")
var ws = new WebSocket("ws://localhost:8000/scanner/node/{nodeID}?token={token}");

ws.onopen = function() {
   ws.send('{"action": "YAGOOD_NODE", "result": {"expectMessageBack": true}}');
};

ws.onmessage = function (evt) {
   console.log(evt.data);
};

Query Parameters

• token should respect the following schema:

{
  "type": "string"
}

Available Actions in Socket

AUTHENTICATE_REQUEST
AUTHENTICATE_ACCEPT
AUTHENTICATE_REJECT
YAGOOD_NODE
REQUEST_BATCH
SEND_BATCH
SEND_BATCH_REJECT
BATCH_ACCEPT_CONFIRM
SUBMIT_RESULTS
RESULTS_ACCEPT_CONFIRM
RESULTS_REJECT
ERROR

Message Structure

{
  "action": "actionType",
  "result": {},
  "error": {
    "fr": false,
    "msg": null
  }
}

Available Errors in Socket

UNK_ER
WR_BAID
SN_BR_LOCK
MAL_MSG
NO_R_F
UNK_ACT
REQ_VAL_ER
F_K_NOF
TOK_REJ
NODE_CON_AL
NO_RH_XAPK

Environment Variables

MASTER_KEY = # Currently not used, maybe deprecated
WEBSERVER_PORT = 8000 # Webserver port
MONGODB_HOST = # Host of MongoDB
MONGODB_PORT = # Port of MongoDB
MONGODB_USERNAME = # Username for MongoDB
MONGODB_PASSWORD = # Password for given username for MongoDB 
MONGODB_DB_NAME = cprhmr # Database name in MongoDB
MONGODB_AUTH_DB = admin # Authentication DB in MongoDB

Running the App

THIS WILL BE CHANGED TO RUNNING THE APP IN DOCKER AFTER THE SEVERAL MORE COMMITS

Firstly, you need to install Python's requirements:

pip3 install -r requirements.tx

Secodnly, complete the .env file.

Finally, run the app:

uvicorn app:app