Nexus Dev
Search…
⌃K

API Builder

API Builder crash course

Overview

Nexus API system is an extremely powerful and extremely fast way to communicate with the Nexus core. Creating or modifying these API's is simple and straight forward. Only requirement is a some basic understanding of coding.
This guide will help you build your own API's.

Parameter Extraction

We need to able to extract the input parameters from our new API. In order to gather information given using your api call, you can use our extractions methods to parse the incoming input.
Extraction methods take in the command line input and returns the requested details.
All methods take a encoding::json& value, commonly seen as jParams , as the FIRST PARAMATER to these methods.

Available Methods:

  • ExtractAddress()
  • ExtractToken()
  • ExtractLegacy()
  • ExtractMarket()
  • ExtractGenesis()
  • ExtractRecipient()
  • ExtractHash()
  • ExtractAmount()
  • ExtractFieldname()
  • ExtractFormat()
  • ExtractScheme()
  • ExtractType()
  • ExtractTypes()
  • ExtractPin()
  • ExtractVerbose()
  • ExtractList()
  • ExtractBoolean()
  • ExtractString()
  • ExtractInterger()
  • ExtractDouble()
Common Example
1
const std::string strAddress = ExtractString(jParams, "address");
If the input in this call is system/foo/bar pin=1234 address=2DSxxxS amount=100 then the above
line of code will extract the value of the key address and return "2DSxxS".

Reading Register / Ledger.

To get register or object information, create a new object then use the ReadObject method to populate the given object.
1
TAO::Register::Object aToken;
2
/** regAddress= the Register Address ; aToken= Object to write to **/
3
LLD::Register->ReadObject(regAddress, aToken))
Example: To read a contract
1
uint256_t hashValidator = 0;
2
/** pair= original contract, hashValidator= address of fulfiller **/
3
if(LLD::Contract->ReadContract(std::make_pair(hashTx, nContract), hashValidator))
4
{
5
...
6
}
There are other LLD classes that you can get to get information from the core's database: Logical, Contract, Register, Ledger, Local, Client, Trust(Legacy) and Legacy.

Contract Input

A contract is combining the finalised logic and attaching our operators to this data. First instantiate a new contract:
1
std::vector<TAO::Operation::Contract> contracts(1);
2
// 1 = number of contracts in this transaction
Then we push our logic in linearly, creating a new contract object already adds the pre and post instructions.
1
/** Set operation , set object to modify , data to write **/
2
vContracts[0] << uint8_t(TAO::Operation::OP::WRITE) << hashRegister << ssPayload.By
To add complexity and conditions by adding more operation and or additional contracts.
​
The simplest way to return info back to the api caller is to simply return a json object. Using encoding::json simply create this object, populate it with key/value pairs and return.
Example:
1
encoding::json jRet;
2
jRet["foo"] = "bar";
3
return jRet;

Create Endpoint

Now in order to use this function we will have to attach an endpoint to it. First determine which API system to add it to, then add it to that system's initialize.cpp file. The systems folders can be found at TAO/API/commands .
1
mapFunctions["get/info"] = Function(std::bind(&System::GetInfo, this, std::placeholC
mapFunctions is our map of functions for the system's container. The key will be the uri that points to your function, so if you want your api to be system/get/info then the key will be get/info, next bind your method, using std::bind place your method in param slot 1. Second slot is this , 3rd and 4th should be placeholder objects.
VERB /NOUNS
A more advance use of Nexus' apis are verbs and nouns. Instead of a single endpoint, you have a verb, like get or list, and a noun, like token or asset. Users can now do endpoints like list/token or get/asset and vice versa with out you explicitly creating those endpoints.
To create a new noun you will use the mapStandards["bar"] = Standard(...) method. Verbs would be created like the api functions above but templated.
Example:
1
mapFunctions["list"] = Function (std::bind (&Templates::List,std::placeholders::_1,

Build API Set

API sets are just collections of api endpoints to make everything easy to understand. For example, system , ledger , names ; All API endpoints manipulating name objects should be housed under names , ETC.
First add a new folder under commands then in that folder create a initialize.cpp file. This file can contain only an Initialize function that modifies mapFunctions and thats it.
1
void FooBar::Initialize(){mapFunctions["foobar"] =
2
Function(std::bind(&FooBar::cmd,this,std::placeholder_1,std::_placeholder_2)}
Your folder should look like this
FooBar ->
initialize.cpp
command1.cpp
command2.cpp ...
Second add a header file to the types folder TAO/API/types/commands/ ie foobar.h . In this file you should have this basic contruction (See the other files for guidance)
👍
​
1
class FooBar : public Derived<FooBar>
2
{public:
3
FooBar() : Derived<FooBar>(){}
4
/** Initialize.* * Sets the function pointers for this API.* **/
5
void Initialize() final;
6
/** Name* * Returns the name of this API.* **/
7
static std::string Name() { return "foobar"; }
8
/** PLACE METHOD CONSRUCTORS HERE **/
9
}
Finally to add a new set to Nexus' api stack, go to src/TAO/API/global.cpp and add the new API set under the rest of the command initializations.
​
1
/* Create the API instances. */
2
Commands::Register<Assets>();
3
+++ Commands::Register<FooBar>();

Finish

Its time to fire up the Nexus core and start using the new API endpoint.