Following we demonstrate and explain the usage of the JSON-REST HTTP interface (API) for an Aidos Node.
Through the API it is possible to request certain information or to execute certain commands on your local or a remote node (depending on which commands are enabled for remote access).
Once your node is successfully setup, you can interface with it through port 14266 by passing along a JSON object which contains a specified command; and upon successful execution of the command, returns your requested information.
The Aidos API is running on port 14266 by default (Testnet: port 15555).
All API calls need to be sent to http://localhost:14266 via a POST HTTP request. The data which will be sent is a JSON object which is defined by the following scheme:
Additional parameters are simply added as additional key-value pairs. If the command is successfully executed, your requested information is returned as either an object or a stringified object (use json.parse or equivalent to turn it into an object).
When making a request, make sure that the HTTP library you're using defines the Content-Length of the data to be sent. If this is not done automatically, manually add it via a header field e.g. 'Content-Length': Buffer.byteLength(JSON.stringify(command)).
Here we list and describe all additional parameters which are required to be passed along for certain commands:
stringtryte encoded string which contains the accounts seed. The seed must be correctly encoded trytes: only uppercase latin letters and 9’s. No other characters are allowed. The maximum security level is 81-trytes, but you can choose longer/shorter seeds.
string81-trytes long address of the recipient of a transaction.
stringthe quantity of units which should be transferred. Note that one ADK equals 100000000 units.
stringtryte-encoded string which can contain arbitrary information and is sent alongside a transaction. The message value is publicly visible. The max value is 2187 trytes, which is 6561 trits (or roughly 1312 bytes).
transaction / hash:
stringhash of a transaction. A single transaction hash is 81-chars long.
stringthe raw data of a transaction.
listcontains a list of transaction bundles. Bundles are basically linked, individual transactions which were created with a single transfer. They are uniquely identified by a 27-char hash.
lista list of addresses. A single address is 81-chars long.
listthe tag of a transaction.
lista list of transaction which were referenced by this transaction
intspecifies the security level of your transaction. Can either by 0 (for 81-trit security), 1 (for 162-trit security) and 2 (for 243-trit security). Lower security transactions are faster to generate.
intspecifies the amount of Proof of Work that will be carried out. Currently can only take the value 18.
The returned value is a different set of tryte values which you can input into
storeTransactions. The returned tryte value, the last 243 trytes basically consist of the:
nonce. These are valid trytes which are then accepted by the network.
The transaction hashes which are returned depend on your input. For each specified input value, the command will return the following:
Returns the list of transactions which contain the specified bundle hash.
Returns the list of transactions which have the specified address as an input/output field.
Returns the list of transactions which contain the specified tag value.
Returns the list of transaction which reference (i.e. confirm) the specified transaction.
List of balances in the same order as you put in the addresses. The balance is returned in units, which means 100000000 = 1 ADK.
List of boolean values in the same order as the transaction list submitted. Returning true/false depending if a transaction is confirmed or not. (refering to the newest milestone (tip) submitted)
Name of app you are currently using. ARI stands for Aidos Reference Implementation
The version of the Aidos software you're currently running.
Available cores on your machine for JRE.
Returns the amount of free memory in the Java Virtual Machine.
Returns the maximum amount of memory that the Java virtual machine will attempt to use.
Returns the total amount of memory in the Java virtual machine.
Latest milestone that was signed off by the coordinator.
Index of the latest milestone.
The latest milestone which is solid and is used for sending transactions. For a milestone to become solid your local node must basically approve the submesh of coordinator-approved transactions, and have a consistent view of all referenced transactions.
Index of the latest solid submesh.
Number of peers you are directly connected with.
Packets which are currently queued up.
Current UNIX timestamp.
Number of tips in the network.
Transactions to request during syncing process.
Trunk Transaction to approve.
Branch Transaction to approve.
Following API calls are used for the peer discovery, thus it's not needed to call any of them manually. The commands are still listed and explained below.
Returns either 0 if your node was already added in a previous call, 1 if it was added now or -1 if it was refused.