mirror of
https://github.com/pezkuwichain/pezkuwi-api.git
synced 2026-11-14 18:37:06 +00:00
SatoshiQaziMuhammed
1914388d2b
* docs: generate the API reference for developers.pezkuwichain.io Add TypeDoc (0.28.20) and `yarn docs`, which builds the reference for the nine public API packages from src/ into build-docs/, with a landing page and a getting-started guide whose examples were run against the live network. The PR workflow builds it so a broken doc comment or config is caught before merge. docs/ held only a redirect to polkadot.js.org; it now holds the guide sources. The README, packages/api/README.md and three CHANGELOG entries linked to js.pezkuwichain.app, a domain that is not ours and is listed for sale; they now point to developers.pezkuwichain.io, the Pezkuwi Portal, or the upstream polkadot.js.org pages the entries came from. * ci(docs): deploy the reference to developers.pezkuwichain.io On every master push that changes the generated reference, build it with `yarn docs` and publish it to the web host the same way pezkuwi-apps publishes the portal: an approved production environment holds the deploy key, the bundle is unpacked into releases/<sha>, and going live is one rename of the current symlink. The switch is checked through nginx for the public name (deploy sha, index, main.js, search index) and rolled back if the new release is not served. workflow_dispatch with rollback_to makes an earlier release live again. Release-bot version bumps ([CI Skip]) and changes that cannot affect the output do not ask for an approval.
101 lines
6.0 KiB
Markdown
101 lines
6.0 KiB
Markdown
# @pezkuwi/api
|
|
|
|
The Pezkuwi-JS API provides easy-to-use wrappers around JSONRPC calls that flow from an application to a node. It handles all the encoding and decoding or parameters, provides access to RPC functions and allows for the query of chain state and the submission of transactions.
|
|
|
|
The API wrappers provide a standard interface for use -
|
|
|
|
- A static `.create(<optional ApiOptions>)` that returns an API instance when connected, decorated and ready-to use. ApiOptions can include an optional WsProvider and optional custom type definitions `{ provider: <Optional WsProvider>, types: <Optional RegistryTypes> }`.
|
|
- The above is just a wrapper for `new Api(<optional ApiOptions>) `, exposing the `isReady` getter
|
|
- `api.rpc.<section>.<method>` provides access to actual RPC calls, be it for queries, submission or retrieving chain information
|
|
- browse them live in the [Pezkuwi Portal, RPC calls](https://js.pezkuwichain.io/#/rpc)
|
|
- `api.query.<section>.<method>` provides access to chain state queries. These are dynamically populated based on what the runtime provides
|
|
- browse them live in the [Pezkuwi Portal, chain state](https://js.pezkuwichain.io/#/chainstate)
|
|
- `api.tx.<section>.<method>` provides the ability to create a transaction, like chain state, this list is populated from a runtime query
|
|
- browse them live in the [Pezkuwi Portal, extrinsics](https://js.pezkuwichain.io/#/extrinsics)
|
|
- `api.consts.<section>.<constant>` provides access to the module constants (parameter types).
|
|
- browse them live in the [Pezkuwi Portal, constants](https://js.pezkuwichain.io/#/chainstate/constants)
|
|
|
|
## API Selection
|
|
|
|
There are two flavours of the API provided, one allowing a standard interface via JavaScript Promises and the second provides an Observable wrapper using [RxJS](https://github.com/ReactiveX/rxjs). Depending on your use-case and familiarity, you can choose either (or even both) for your application.
|
|
|
|
- [[ApiPromise]] All interface calls returns Promises, including the static `.create(...)`. Additionally any subscription method uses `(value) => {}` callbacks, returning the value as the subscription is updated.
|
|
- [[ApiRx]] All interface calls return RxJS Observables, including the static `.create(...)`. In the same fashion subscription-based methods return long-running Observables that update with the latest values.
|
|
|
|
## Dynamic by default
|
|
|
|
Bizinikiwi (upon which Pezkuwi is built) uses on-chain WASM runtimes, allowing for upgradability. Each runtime defining the actual chain extrinsics (submitted transactions and block intrinsics) as well as available entries in the chain state. Due to this, the API endpoints for queries and transactions are dynamically populated from the running chain.
|
|
|
|
Due to this dynamic nature, this API departs from traditional APIs which only has fixed endpoints, driving use by what is available by the runtime. As a start, this generic nature has a learning curve, although the provided documentation, examples and linked documentation tries to make that experience as seamless as possible.
|
|
|
|
## Installation & import
|
|
|
|
Installation -
|
|
|
|
```
|
|
npm install --save @pezkuwi/api
|
|
```
|
|
|
|
Subscribing to blocks via Promise-based API -
|
|
|
|
```javascript
|
|
import { ApiPromise } from '@pezkuwi/api';
|
|
|
|
// initialise via static create
|
|
const api = await ApiPromise.create();
|
|
|
|
// make a call to retrieve the current network head
|
|
api.rpc.chain.subscribeNewHeads((header) => {
|
|
console.log(`Chain is at #${header.number}`);
|
|
});
|
|
```
|
|
|
|
Subscribing to blocks via RxJS-based API -
|
|
|
|
```javascript
|
|
import { ApiRx } from '@pezkuwi/api';
|
|
|
|
// initialise via static create
|
|
const api = await ApiRx.create().toPromise();
|
|
|
|
// make a call to retrieve the current network head
|
|
api.rpc.chain.subscribeNewHeads().subscribe((header) => {
|
|
console.log(`Chain is at #${header.number}`);
|
|
});
|
|
```
|
|
|
|
## Registering custom types
|
|
|
|
Additional types used by runtime modules can be added when a new instance of the API is created. This is necessary if the runtime modules use types which are not available in the base Bizinikiwi runtime.
|
|
|
|
```javascript
|
|
import { ApiPromise } from '@pezkuwi/api';
|
|
|
|
// initialise via static create and register custom types
|
|
const api = await ApiPromise.create({
|
|
types: {
|
|
CustomTypesExample: {
|
|
"id": "u32",
|
|
"data": "Vec<u8>",
|
|
"deposit": "Balance",
|
|
"owner": "AccountId",
|
|
"application_expiry": "Moment",
|
|
"whitelisted": "bool",
|
|
"challenge_id": "u32"
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
## Users
|
|
|
|
Some of the users of the API (let us know if you are missing from the list), include -
|
|
|
|
- [Pezkuwi-JS UI](https://github.com/pezkuwichain/pezkuwi-apps) A user-interface that allows you to make transactions, query the network or participate in actions on the network such as referendums and staking
|
|
- [KodaDot](https://github.com/vue-pezkuwi/apps) ([twitter](https://twitter.com/KodaDot)) - Vue.js web wallet, governance dashboard and aspiring performance (lightweight) alternative to original apps, mobile-first.
|
|
- [Polkabot](https://gitlab.com/Polkabot) Polkabot is a Matrix chatbot that keeps an eye on the Pezkuwi network. You can see Polkabot in action in https://matrix.to/#/#pezkuwi-network-status:matrix.org
|
|
- [Polkawallet.io](https://polkawallet.io) and [Polkawallet (Github)](https://github.com/polkawallet-io/polkawallet-RN/) A mobile wallet for the Pezkuwi network to manage funds and make transactions, available on both Androind and iOS
|
|
- [PolkaStats.io](https://polkastats.io), [PolkaStats frontend GitHub repository](https://github.com/Colm3na/polkastats-v2) and [PolkaStats backend GitHub repository](https://github.com/Colm3na/polkastats-backend-v2) Pezkuwi network statistics (currently Zagros and Alexander). Shows network information and staking details from validators and intentions.
|
|
- [Pezkuwi API Server (GitHub)](https://github.com/SimplyVC/pezkuwi_api_server) A lightweight server for querying Pezkuwi nodes from any language, built primarily as a backend for [PANIC for Pezkuwi (GitHub)](https://github.com/SimplyVC/panic_pezkuwi/), a validator monitoring and alerting tool.
|
|
- [Identity Registrar #1 from Chevdor on Zagros, Zagros and Pezkuwi](https://www.chevdor.com/tags/registrar/)
|