API client
The Lisk Elements API Client provides a convenient wrapper for interacting with the public API of nodes on the Lisk network.
Installation
This adds Lisk Client as a dependency of your project:
$ npm install @liskhq/lisk-api-client@3.0.1
APIClient
Syntax
new APIClient(nodes, [options])
APIClient.createMainnetAPIClient([options])
APIClient.createBetanetAPIClient([options])
APIClient.createTestnetAPIClient([options])
Parameters
nodes
: When calling the constructor directly, a list of nodes must be provided for the API client to connect to as an array of strings.
options
: An additional configuration for the client can be specified via an optional option object:
-
bannedNodes
: These are an array of nodes which should not be used, (this overrides the array of nodes used to initialise the client). -
client
: This is an object specifying certain details about your client, which will be included as part of theUser-Agent
header when sending HTTP requests. Available keys are as follows:name
,version
andengine
. -
genesisBlockPayloadHash
: This is the genesis payload hash of the network which your client will interact with. -
node
: This is the node to use first, (this overrides the order of the array of nodes used to initialise the client). -
randomizeNodes
: This specifies whether a random node should be selected after one becomes unreachable. (Default value:true
.)
Examples
const { APIClient } = require('@liskhq/lisk-api-client');
const client = new APIClient(['https://node01.lisk.io:443', 'https://node02.lisk.io:443']);
const clientWithOptions = new APIClient(
['https://node01.lisk.io:443', 'https://node02.lisk.io:443'],
{
bannedNodes: ['https://my.faultynode.io:443'],
client: {
name: 'My Lisk Client',
version: '1.2.3',
engine: 'Some custom engine',
},
genesisBlockPayloadHash: '9a9813156bf1d2355da31a171e37f97dfa7568187c3fd7f9c728de8f180c19c7',
node: 'https://my.preferrednode.io:443',
randomizeNodes: false,
}
);
const mainnetClient = APIClient.createMainnetAPIClient();
const testnetClient = APIClient.createTestnetAPIClient();
const betanetClient = APIClient.createBetanetAPIClient({ randomizeNodes: false });
Constants
API-specific constants are available via the APIClient
constructor, and include relevant HTTP methods and lists of default nodes.
Examples
const { APIClient } = require('@liskhq/lisk-api-client');
APIClient.constants.GET;
APIClient.constants.POST;
APIClient.constants.PUT;
APIClient.constants.TESTNET_NETHASH;
APIClient.constants.MAINNET_NETHASH;
APIClient.constants.TESTNET_NODES; (1)
APIClient.constants.MAINNET_NODES; (2)
1 | Array of default Testnet nodes. |
2 | Array of default Mainnet nodes. |
Methods associated with a resource
Requests to a node are made via the APIClient
instance’s respective resource, and return a promise.
In the case of a response with a status code in the 2xx
range, these promises are fulfilled with a relevant object, otherwise they are rejected with an appropriate error message.
Documentation for each resource can be found on the following pages:
Methods not associated with a resource
initialize
This initialises the client instance with an array of nodes and an optional configuration object. This is called in the constructor, however, this can be called again later if necessary. (Note that in practice it is usually easier just to create a new instance.)
Examples
client.initialize(['https://node01.lisk.io:443', 'https://node02.lisk.io:443']);
client.initialize(
['https://node01.lisk.io:443', 'https://node02.lisk.io:443'],
{
bannedNodes: ['https://my.faultynode.io:443'],
client: {
name: 'My Lisk Client',
version: '1.2.3',
engine: 'Some custom engine',
},
genesisBlockPayloadHash: '9a9813156bf1d2355da31a171e37f97dfa7568187c3fd7f9c728de8f180c19c7',
node: 'https://my.preferrednode.io:443',
randomizeNodes: false,
}
);
banNode
This adds a node to the list of banned nodes. Banned nodes will not be chosen to replace an unreachable node.
banActiveNodeAndSelect
This bans the current node and selects a new random node that has not previously been banned.