Reading Time: 3 minutes

The API provides application developers the ability to query a node and interact with the Polkadot or Substrate chains using Javascript. Hello Readers, today we will see what is a polkadot.js API.

These sections should provide you with all the information needed to install the @polkadot/api package, understand the structure of the interfaces and allow you to start using it. For existing users this really should be titled “Things I wish I knew before I started using the api” . It really aims to close the gap to allow anybody to get to grips with using the packages.

ES2015 Usage and examples

Just to be aware that in all cases we are using ES2015, including using things like async/await, import and others. Depending on your environment, this may require some adjustments.

While we are using the await naked in all examples (this removes boilerplate and allows us to focus on the actual libraries), and unless your environment supports top-level await, it will need to be wrapped in an async block. So basically to make it run-able we should wrap all samples inside a async function main () { ... } and then just call main().then(() => console.log('completed')).

In the case of Node.js you would change the import into require, i.e.

// Import
const { ApiPromise, WsProvider } = require('@polkadot/api');
...

While Node.js versions >=12 support the import syntax, we are only exporting CommonJS modules, hence the need for require.

Installation

Yes, it really is as simple as installing from npm, so we are not going to waste too much time with the bare basics, just install the API via

yarn add @polkadot/api

The above will always install the latest stable release, which should allow you to connect to test networks and local nodes that are tracking versioned releases for Polkadot and Substrate.

Betas

For users who have a slightly higher appetite for risk, or are using bleeding-edge master branches of either Polkadot/Substrate.

We also publish a beta version as soon as anything is merged into the API master branch. This version really contains all the latest fixes and features and is the version we actually use inside the polkadot-js projects – eating our own dog food.

To install a beta version, either to test or for support of a feature that is available in Substrate master (and has not yet made it to a stable api release), you can install it via the @beta tag, i.e.

yarn add @polkadot/api@beta

Other dependencies

In most cases, you don’t need to do anything else apart from just installing @polkadot/api above. It has dependencies such as @polkadot/types which are installed automatically alongside. When using yarn the dependencies are installed, flattened, available for use and you will never run into issues with mismatched versions.

This means that by simply installing @polkadot/api, you will have access to utilities (crypto and normal), types, providers and even higher-order (derived) API functions. (We will get to all of these in follow-up sections)

If you do however decide to explicitly install other packages (even though they are dependencies), please make sure that the versions inside the api package always match with your versions, i.e. if you installed @polkadot/api 2.1.2-3 and you have your own version of @polkadot/types, ensure that it is also 2.1.2-3.

Thank You For Reading this blog, stay connected for more content on polkadot.js APIs

If you want to read more content like this?  Subscribe to Rust Times Newsletter and receive insights and latest updates, bi-weekly, straight into your inbox. Subscribe to Rust Times Newsletter: https://bit.ly/2Vdlld7.