Skip to main content

Getting started

Buildcore API provides various ways to interact with our platform. The recommended one is the @build-5/sdk which interacts through a REST API and our so called OTRs with the Buildcore platform.

SDK​

Just add the SDK to your project and get startet:

npm i @build-5/sdk
npm i @build-5/interfaces

The sdk is split into two modules to interact with the Buildcore platform. otr and https. Checkout the following sections to lern more.

info

To create Requests we recommend using the OTR method instead of POST requests and only use the https module to monitor the Tangle or create get information from the backend.

OTR​

On tangle requests are a secure and transparent way to interact with Buildcore products. They are a way to send a request to a Buildcore backend over the Tangle as a transaction. The backend will then execute the request encoded in the OTR. All interactions can be verified on the Tangle.

As you see in the chart above, the workflow of working with OTR is the following:

  1. Prepare the OTR data with the SDK and create a Deeplink for the request.
  2. Clicking the Deeplink in for example a dApp frontend will open the specific wallet with a preconfigured transaction to create the OTR. The OTR is a transaction on the Tangle to a specific OTR Address with encoded metadata.
  3. The Buildcore Backend (a so called Verse) will monitor the tangle and check if OTRs where send to its (OTR-)Address. If so the request will be handled and if necessary assets or a response will be send back to the caller/wallet via Tangle.
  4. The SDK can monitor the transaction with an Observable object and check its status.

Example​

To use OTR with the SDK you need to choose an OTR Address and create an otrWrapper object. Checkout this small example:

import { Dataset } from '@build-5/interfaces';
import { SoonaverseOtrAddress, otr } from '@build-5/sdk';

async function main() {
  const otrRequest = otr(SoonaverseOtrAddress.TEST)
    .dataset(Dataset.NFT)
    .mintMetadataNft({
      metadata: { prop1: 'prop1', prop2: 'prop2' },
    });
  console.log(otrRequest.getFireflyDeepLink());
}
main().then(() => process.exit());
Development Environment

You can specify the environment you want to work in, by using the specific OTR Address. In the SDK you can use the SoonaverseOtrAddress enum to get the correct address.

HTTPS​

The SDK also provides a wrapper for Buildcores API.

info

We are in the process of migrating POST requests to OTR.

As you see in the chart above, the workflow of working with HTTPS POST is the following:

  1. The SDK creates a POST request. This request has to be signed by either a web3 wallet like Metamask or Tanglepay. The response will contain specific Address for this request from the Buildcore backend (so called verse).
  2. This Address can than be used by a wallet to send the needed funds/assets for the request.
  3. The Buildcore Verse will monitor the tangle and check if funds/assets where send to the Address. If so the request will be handled and if necessary assets or a response will be send back to the caller via Tangle.
  4. The SDK can monitor the transaction with an Observer and check its status.

Example​

To interact with the API you need to choose an endpoint you want to connect to and create an httpsWrapper object. Let's do a simple GET Request to get the member's object of Santa Claus:

import { Dataset } from '@build-5/interfaces';
import { Build5, SoonaverseApiKey, https } from '@build-5/sdk';

async function main() {
  var members = await https(Build5.TEST)
    .project(SoonaverseApiKey[Build5.TEST])
    .dataset(Dataset.MEMBER)
    .getByField('name', 'Santa Claus');
  console.log(members);
}
main().then(() => process.exit());

API Endpoints and Keys​

We provide two endpoints. One for testing and one for production. In the SDK you can access them with the Build5 enum. You can also find them here:

https://api.buildcore.io

Make sure to consider API's limitations

API Keys

To work with the API you need access keys which you can get by creating a project. You can also use public Soonaverse keys to test against live community driven project. In the SDK you can access the following Keys through the SoonaverseApiKey constant.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIweDU1MWZkMmM3YzdiZjM1NmJhYzE5NDU4N2RhYjJmY2Q0NjQyMDA1NGIiLCJwcm9qZWN0IjoiMHg0NjIyM2VkZDQxNTc2MzVkZmM2Mzk5MTU1NjA5ZjMwMWRlY2JmZDg4IiwiaWF0IjoxNzAwMDAyODkwfQ.IYZvBRuCiN0uYORKnVJ0SzT_1H_2o5xyDBG20VmnTQ0

Limitations​

We only allow:

  • unlimited number of requests on OTR through Tangle - recommended!
  • maximum of 50 requests per second on GET requests
  • maximum of 5 requests per second on POST requests

If you need higher throughput make sure to reach out to use so we can enable higher throughput for you.

This limits are necessary to avoid abuse and dDos attacks.

See some of our first how to's:​