Lisk Elements API Client
The Lisk Elements API Client provides a convenient wrapper for interacting with the public API of nodes on the Lisk network.
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
: Additional configuration for the client can be specified via an optional option object:
-
bannedNodes
: An array of nodes which should not be used (overrides the array of nodes used to initialise the client). -
client
: An object specifying certain details about your client, which will be included as part of theUser-Agent
header when sending HTTP requests. Available keys arename
,version
andengine
. -
nethash
: The nethash of the network your client will interact with. -
node
: The node to use first (overrides the order of the array of nodes used to initialise the client). -
randomizeNodes
: Whether a random node should be selected after one becomes unreachable. (Default:true
.)
Examples
import * as APIClient from '@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',
},
nethash: '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
import APIClient from '@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
Initialises the client instance with an array of nodes and an optional configuration object. This is called in the constructor, but 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',
},
nethash: '9a9813156bf1d2355da31a171e37f97dfa7568187c3fd7f9c728de8f180c19c7',
node: 'https://my.preferrednode.io:443',
randomizeNodes: false,
}
);
banNode
Adds a node to the list of banned nodes. Banned nodes will not be chosen to replace an unreachable node.