These instructions describe HTTP methods, URL paths, and HTTP message bodies. For example, send an authentication request like this:
Method: POST
Path: /wallet/auth
Body: {"wallet": "<name>", "password": "<password>"}
You can substitute those values into the following sample of JavaScript code for a NodeJS environment.
//-- JavaScript for NodeJS ----------------
//
// Set 5 variables below.
// For the body, sometimes supply a JSON data object.
// Sometimes supply six characters: "null"
// bearerToken is the value returned by your first request:
// POST /wallet/auth {"wallet": "<name>", "password": "<password>"}
// A bearerToken remains valid for about one year.
//
// Modify 2 functions below to suit your need:
// handleReply() and handleError()
//
//-- Set 5 variables ----------------------
var config={
method:"<Method>",
path:"<Path>",
body:<Body>,
apikey:"<yourApiKeyFromGreenstand>",
bearerToken:"<bearerToken>",
host:"prod-k8s.treetracker.org"
} // end config
//
//-- Handle reply -------------------------
const handleReply=function(code,msg,obj){
console.log(code+': '+msg);
console.log(obj);
} // end handleReply
//
//-- Handle error -------------------------
const handleError=function(src,code,msg,body){
console.log(src);
console.log(code+': '+msg);
console.log(body);
} // end handleError
//
//-- Function to send request -------------
const https=require('https');
const sendRequest=function(){
try{
//-- Define request -------------------
let options={
"method":config.method,
"hostname":config.host,
"path":config.path,
"headers":{
"TREETRACKER-API-KEY":config.apikey,
"Content-Type":"application/json",
"Authorization":"Bearer "+config.bearerToken
},
"maxRedirects":20
};
var req = https.request(options,function(reply){
//-- Handle response ----------------
reply.on("error",function(err){handleError('Reply error',499,err,null);});
var chunks = [];
reply.on("data",function(chunk){chunks.push(chunk);});
reply.on("end",function(){
let code=parseInt(reply.statusCode);
let msg=reply.statusMessage;
let body=Buffer.concat(chunks).toString();
let obj=null;
try{obj=JSON.parse(body);}
catch(e){handleError('JSON parse error',code,msg,body);return;}
if((code<200)||(code>299)){handleError('Reply code error',code,msg,obj);return;}
handleReply(code,msg,obj);
});
});
//-- If request has a body, send it ---
if((config.body)&&(typeof config.body=='object')){
req.write(JSON.stringify(config.body));
}//if
//-- end ------------------------------
req.end();
}//try
catch(err){handleError('sendRequest() error',499,err,null);}
}// end sendRequest
//
//-- Execute ------------------------------
sendRequest();
//-- End JavaScript -----------------------
//-----------------------------------------
For Bash and cURL on Mac or Linux, here is sample code.
# -- Bash and cURL -------------------------
#
# Set 5 variables below.
# Path values usually need 'quotes.'
# For the body, sometimes supply a JSON-formatted string
# inside single quotes: '{"key":"value"}'
# Sometimes supply four characters: null
# Boolean values need quotes '{"name":"true"}'
# bearerToken is the value returned by your first request:
# POST /wallet/auth {"wallet": "<name>", "password": "<password>"}
# A bearerToken remains valid for about one year.
#
# -- Set 5 variables -----------------------
method=<Method>
path='<Path>'
body='<Body>'
#body=null
apikey='TREETRACKER-API-KEY:'<yourApiKeyFromGreenstand>
bearerToken=<bearerToken>
host='https://prod-k8s.treetracker.org'
type='Content-Type:application/json'
#
# -- Send request --------------------------
if [[ $body == "null" ]]; then
curl -L -X $method $host$path -H $apikey -H $type -H 'Authorization: Bearer '${bearerToken}
fi
if [[ $body != "null" ]]; then
curl -L -X $method $host$path -H $apikey -H $type -H 'Authorization: Bearer '${bearerToken} -d $body
fi
# -- End Bash ------------------------------
Every new user of the API needs to start with an authentication request.
That request returns a "bearer token," a string of 852 characters that goes in the header of all subsequent requests. Without it, requests return an error. A bearer token is valid for about one year.
Send this request:
Method: POST
Path: /wallet/auth
Body: {"wallet": "<nameOfYourTreetrackerWallet>", "password": "<yourWalletPassword>"}
The API responds with:
200: OK
{ token: "<852characters>" }
In subsequent requests, include this header
"Authorization":"Bearer <852characters>"
If you do not, or if the bearer token has expired, the API responds with:
Now Alice can direct Bob (or anyone else) to find his trees on the map:
https://map.treetracker.org/?wallet=BobsWallet
Note that Bob does not manage his wallet. Alice does. BobsWallet does not have its own password. Bob cannot use the API. Only Greenstand administrators can create a new user account with a new managed wallet.
Alice is Bob's business partner. She often transfers tokens to Bob's wallet. So often, that it is a nuisance for Bob to explicitly accept each and every transfer.
So Alice and Bob create a trust relationship, as follows.
From now on, Alice can transfer tokens to Bob without Bob's explicit permission. Alice can POST /wallet/transfers and the tokens will immediately move to BobsWallet. Bob does not need to find the transfer id and POST /wallet/transfers/<transfer_id>/accept.
For a long time, Bob has trusted Alice to transfer tokens into his wallet whenever she wants. But Alice and Bob have moved on to different businesses. They need to break that trust relationship.
Either of them can do so:
Either of them finds the necessary trust relationship ID:
Method: GET
Path: /wallet/trust_relationships?limit=99&state=trusted
The API replies with an array of trust objects:
200: OK
{ trust_relationships: [ {<trust_relationship>},{<trust_relationship>},{<trust_relationship>}, ... ] }
In that array, they find the trust that let's Bob receive transfers from Alice:
