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

This adds Lisk Client as a dependency of your project:

$ npm install @liskhq/lisk-api-client

Upgrade

npm update @liskhq/lisk-api-client

APIClient

A constructor is exposed, which takes an array of nodes, and optionally an options object. For convenience, helper functions are provided for creating API clients on specific networks with a default set of nodes. It is recommended to use these functions unless you are operating your own nodes, or there is a preference to use nodes provided by a third party.

If the generic constructor is used, it is the user’s responsibility to ensure that the specified nodes 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: 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 the User-Agent header when sending HTTP requests. Available keys are as follows: name, version and engine.
nethash: This is the nethash 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.)

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

This 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

This 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

This 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

This 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

This provides the details as to which nodes have been banned.

Syntax

hasAvailableNodes()

Parameters

n/a

Return value

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

Examples

const moreNodesNeeded = !client.hasAvailableNodes();

isBanned

This provides the details of whether a specific node has been banned.

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');