#
Extending Chain
When writing an advanced Hive blockchain application, you may want to add more APIs to the standard set of Wax methods. There is a feature in Wax called extend or extendRest (for REST API) allowing you to extend Wax Chain with fully-typed requests with full typization.
#
Manually extending JSON-RPC API
import { createHiveChain, TWaxApiRequest } from '@hiveio/wax';
const chain = await createHiveChain();
interface IsKnownTransactionRequest {
id: string;
}
interface IsKnownTransactionResponse {
is_known: boolean;
}
// Create the proper API structure
type TExtendedApi = {
database_api: { // API
is_known_transaction: TWaxApiRequest<
IsKnownTransactionRequest,
IsKnownTransactionResponse
>; // Method
}
};
const extended = chain.extend<TExtendedApi>();
// Call the database_api API using our extended interface
const result = await extended.api.database_api.is_known_transaction({
id: "0000000000000000000000000000000000000000"
});
console.info(result);{ "is_known": false }As you can see in the example, there is a type called: TWaxApiRequest which as a first template argument takes a user input type (that the user will have to pass to the API request function). It may be an interface, but it can also be a standard type, like: boolean, number, Array and so on. The second argument should be the response type (type of result in the snippet above).
TBA
#
Manually extending REST API
import { createHiveChain } from '@hiveio/wax';
const chain = await createHiveChain();
interface BlockHeaderRequest {
blockNum: number;
}
interface BlockHeaderResponse {
witness: string;
previous: string;
timestamp: string;
extensions: object[];
transaction_merkle_root: string;
};
// Note: We have to first provide the type of our API with
// proper structure in the generics for IntelliSense
const extended = chain.extendRest<{
hafahApi: {
blocks: {
blockNum: {
header: {
params: BlockHeaderRequest;
result: BlockHeaderResponse;
}
}
}
}
}>
// Then here we provide the implementation details as
// a function argument for runtime evaluation.
// This helps to deduce template values in the URL
// (provided {} characters) and potentially change HTTP methods
({
hafahApi: {
urlPath: 'hafah-api',
blocks: {
blockNum: {
urlPath: '{blockNum}',
header: {
method: 'GET'
}
}
}
}
});
// Call the hafah API using our extended interface
const result = await extended.restApi.hafahApi.blocks.blockNum.header({
blockNum: 12345678
});
console.info(result);{
previous: '00bc614d58b1745f3347e4f55f35fe68c82ad0d1',
timestamp: '2017-05-29T06:28:42',
witness: 'good-karma',
transaction_merkle_root: '3843fd6daebf3742ecc84fe5926df037131a66a6',
extensions: []
}TBA
#
Automatically extending API
Thanks to the OpenAPI specifications, we can automatically generate API definitions for both JSON-RPC and REST API. This way you don't have to manually define each method, its parameters, and return types. If you have your own API with OpenAPI spec, you can also automatically generate the types and use them with Wax.
When dealing with TypeScript and JavaScript, you can use the following package to automatically generate types from OpenAPI spec:
TBA
#
Use JSON-RPC API packages
For basic wax usage, the default API methods, shipped with the package are usually sufficient. However, if you want to use more advanced API methods, you can extend the default API with additional methods. Defining a whole set of methods can be tedious, so Wax provides a way to automatically extend the API with additional methods, using the extend method and external packages with automatically generated spec from OpenAPI.
Example usage:
import JsonRPC from "@hiveio/wax-api-jsonrpc";
const extendedChain = chain.extend(JsonRPC);
// You can now call extendedChain.api[apiType][apiMethod](dataToSend)TBA
#
Use REST API packages
As you can see it is a little complicated and REST API can potentially change frequently as it is not consensus-based, so we created multiple packages, automatically generating API definitions from OpenAPI definitions for each endpoint. You would only need to install the package and use the generated types:
View Reputation Tracker API package on npmjs ðŸ¡
View Balance Tracker API package on npmjs ðŸ¡
Example usage:
import HAfAH from "@hiveio/wax-api-hafah";
const extendedChain = chain.extendRest(HAfAH);
// You can now call extendedChain.restApi...<methodNames>()TBA