Protocol description
  • 22 Mar 2022
  • 2 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Protocol description

  • Dark
    Light
  • PDF

Before you can start using Corezoid API you need to create an API key and get an API login (authorization login) and a secret key.
You can these from the Corezoid menu by following the path:
Users & Groups -> Create -> API key -> enter name -> OK

create_api_key

You may want to create a pre-request script to be able to generate signatures for the API requests you send (via Postman, for example). For creating a pre-request script, you need to copy the {API_LOGIN} authorization login, and {SECRET} secret key (by clicking the icon to the right in your API keys list), and use the following URL:

https://api.corezoid.com/api/2/json/{API_LOGIN}/{TIMESTAMP}/{SIGNATURE}

Where:

  • {API_LOGIN} - authorization login of your API key;

  • {TIMESTAMP} - request time, a Unix timestamp (epoch time) by Greenwich (GMT+0). Requires an integer parameter;

  • {SIGNATURE} - concatenated string generated from the following parts:

hex( sha1({TIMESTAMP} + {SECRET} + {CONTENT} + {SECRET}) )
where:

  • {TIMESTAMP} - request time, a Unix timestamp (epoch time) by Greenwich (GMT+0). Requires an integer input;
  • hex() - converts binary data to hexadecimal form;
  • sha1() - standard hash-function SHA-1, must return binary data;
  • + - text string concatenation;
  • {SECRET} - the secret key for your API key;
  • {CONTENT} - request body.

Now you can use the following script for signing your requests:

var time = Math.floor(Date.now() / 1000);
var secret = pm.environment.get("SECRET");
var content = request.data;
var signature = CryptoJS.enc.Hex.stringify(CryptoJS.SHA1(time + secret + content + secret));
pm.environment.set("TIMESTAMP", time);
pm.environment.set("SIGNATURE", signature);

The entire API request is an http-body described as the {CONTENT} in the {SIGNATURE} formula. All text is expected to be encoded as UTF-8.

Sending an API request requires setting the following HTTP header:

Content-type: application/json; charset=utf8

Request

The request body contains a list of operations (ops):

{
  "ops": [
    {
      "id": 1,
      "type": "create",
      "obj": "conv"
    },
    {
      "type": "modify",
      "obj": "node",
      "obj_id": "n1234"
    }
  ]
}
id optional parameter

The id parameter ("string" format) is optional and is used for identifying operations in the ops array. If not specified, the parameter is returned with an empty value ("id": "") in the response.

Response

{
  "request_proc": "ok",
  "ops": [
    {
      "id": 1,
      "obj": "conv",
      "obj_id": "1234",
      "proc": "ok"
    },
    {
      "id": "",
      "obj": "node",
      "obj_id": "n1234",
      "proc": "obj_id_not_found"
    }
  ]
}
parameter value description
request_proc "ok" in the case of a successful request, otherwise - error global status of whole package processing
ops [] list of operations
ops[n].proc "ok" in the case of a successful request, otherwise - error status for a separate operation