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.

Installation

Add Lisk Client as a dependency of your project:

$ npm install @liskhq/lisk-api-client

Upgrade

npm update @liskhq/lisk-api-client

APIClient

We expose a constructor, which takes an array of nodes, and optionally an options object. For convenience, we provide helper functions for creating API clients on specific networks with a default set of nodes. We recommend using these functions unless you operate your own nodes, or have good reasons to prefer nodes provided by a third party.

If you use the generic constructor, it is your responsibility to ensure that the nodes you specify are on the correct network.

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 the User-Agent header when sending HTTP requests. Available keys are name, version and engine.
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.)

Return value

Instance of APIClient.

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.)

Syntax

initialize(nodes, [options])

Parameters

The parameters are the same as for the constructor.

Return value

undefined

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,
    }
);

getNewNode

Selects a random node that has not been banned.

Syntax

getNewNode()

Parameters

n/a

Return value

string: One of the node URLs provided during intialisation.

Examples

const randomNode = client.getNewNode();

banNode

Adds a node to the list of banned nodes. Banned nodes will not be chosen to replace an unreachable node.

Syntax

banNode(node)

Parameters

node: String URL of the node that should be banned.

Return value

boolean: false if the node is already banned, otherwise true.

Examples

client.banNode('https://my.faultynode.io:443');

banActiveNodeAndSelect

Bans the current node and selects a new random (non-banned) node.

Syntax

banActiveNodeAndSelect()

Parameters

n/a

Return value

boolean: false if the current node is already banned, otherwise true.

Examples

client.banActiveNodeAndSelect();

hasAvailableNodes

Tells you whether all the nodes have been banned or not.

Syntax

hasAvailableNodes()

Parameters

n/a

Return value

boolean: false if all nodes have been banned, otherwise true.

Examples

const moreNodesNeeded = !client.hasAvailableNodes();

isBanned

Tells you whether a specific node has been banned or not.

Syntax

isBanned(node)

Parameters

node: String URL of the node to check.

Return value

boolean: true if the node has been banned, otherwise false.

Examples

const banned = client.isBanned('https://node01.lisk.io:443');