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 the Lisk API client as a dependency to your project:
$ npm install @liskhq/lisk-api-client@4.0.0
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 initialize 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 initialize 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
instances 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 initializes the client instance with an array of nodes and an optional configuration object. This is called in the constructor, and 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.