7.2 KiB
api users and backend developers
api documentation for routes and middleware has to respect apidoc's rules https://apidocjs.com/
To update this doc accessible in https://wal-ants.ndda.fr/cdn/apidoc :
yarn apidoc
For api tribe's doc accessible in https://smatchit.io/cdn/apidoc :
yarn apidoctribename
A special tribe call adminapi is replicated in any towns (node), it works the same than all the other tribe except that all their data are synchronize with a blockchain
Objects manage by adminapi are: pagans (numerique id =alias/public key / private key), notifications (cypher message betxeen alias) , nations (rules apply to all towns belonging to a nations), towns ( a server that host IT ressources disk space, ram, bandwith and rules aplly to all tribe belonging to a town), tribes (( a sharing space to store data as well as api with rules to any person that use it), wwws (web space, dns)
All others object are managed by spécifics tribe.
/townName_nationName/
/conf/nginx/tribename_appname.conf # nginx conf
/conf/apidoc # apidoc conf
/conf/townconf.json # town settings contain all glabl parameter
/tribes/idx/triebid_all.json # A global file {tribename:{conf}
/itm/tribename.json # Config file of a tribe
/adminapi # Tribes synchronize with all town
/apxtri # git yarn/npm project package.json entry point apxtri.js
/routes/
/models/
/middlewares/
/logs/nginx # nginx log related to /conf/nginx/apxtri_adminapi.conf
/api
/objects/objectname/idx/ # list of index to search objectname items
/itms/ # 1 json per items name apxid.json where apxid is a unique key
/wwws/idx/
/itm/
appname.json # website appname conf
cdn.json
/appname/ # website files
/cdn/ # cached files to optimize nginx static file delivery
/schema/conf.json # list of schema and version
/objectname.json # schema title and escription are in english
/lg/objectname_lg.json # title and description in lg
/tribename/ # same than adminapi for a specific tribe but wit /api instead of /apxtri,
# we only have 1 node process that manage 1 town that manage many tribes api
API Endpoint url: /api/{tribename}/{routename}/xxx
Domaine name can be a adminapi donaim name aswell any tribe's domain name. Check nginx conf in /conf/nginx
Object management (Odmdb)
An object has a name and is defined by a schema that contain properties key.
A propertie has a name and a list of caracteristics (type, pattern,format,...) that have to be validate to be accepted.
All properties respect the rules https://json-schema.org/draft/2020-12/schema, some extra"format" can be add to mutualise recurrent regex pattern
To access a schema https://wall-ants.ndda.fr/nationchains/schema/nations.json and language specifique https//:wall-ants.ndda.fr/nationchains/schema/lg/nations_fr.json
A checkjson.js is available to manage all specific format https://wall-ants.ndda.fr/Checkjson.js see Odmdb - schema Checkjson
Additional properties that not exist in 2020-12/schema :
required: an array of required properties
apxid: the propertie used as an unique id
apxuniquekey: array of unique properties
apxidx : array of index
apxaccessrights: object with key profilname and accessrights on properties {profilname:{C:[properties array],R:[properties array],U:[],D:[]}}
Items of an object are store in files into :
/objectnames/idx/keyval_objkey.json
/objectnames/itm/uniqueid.json
api pre-request
Valid header see Middlewares
App use openpgp.js lib to sign xdays_xalias with a privatekey and store it in xhash.
/middlewares/isAuthenticated.js check if (xhash) is a valid signature of the public key a xhash is valid for 24 hours
See Pagans models that contain authentification process
api Return in 3 data structure:
A - data file from a classical get https://wall-ants.ndda.fr/Checkjson.js
B - a json single answer {status, ref,msg,data}:
- status: http code return
- ref: model/route name reference where message come from
- msg: a message template key store into models/lg/name_lg.json (where lg is 2 letters language)
- data: an object data use to render the value of the message key.
C - a json multi answer {status,multimsg:[{ref,msg,data}]}
Each {ref,msg,data] work the same way than B
To show feedback context message in a language lg => get /nationchains/models/{{ref}}_{{lg}}.json
This contain a json {msg:"mustache template string to render with data"}
Accessrights:
An alias is just an identity, to access a tribe, a person must exist with an authenticated alias into /tribes/{tribename}/objects/persons/itm/{alias}.json
A person has a property profils with a list of profilename, common profiles are : anonymous (no identity) / pagan (an identity) / person (an identity with access right into a tribe) / druid (the administrator of a tribe) / mayor (administrator of a town/server)
Each object has an apxaccessrights that is a list of profil and CRUD access per object key .
Add tribe's api:
Accessible with https://dns/api/tribename/routes
/tribes/tribename/api/routes
/tribes/tribename/api/middlewares
/tribes/tribename/api/models
/tribes/tribename/schema
/tribes/tribename/schema/lg
// Example of a route
const tribe="smatchit";
const conftrib = require(`../../../itm/${tribe}.json`);
const conf = require(`../../../conf.json`);
const express = require(`../../../adminapi/apxtri/node_modules/express`);
const fs = require(`../../../adminapi/apxtri/node_modules/fs-extra`);
const Nofications = require(`../../../adminapi/apxtri/models/Notifications.js`);
const Appscreens = require(`../models/Appscreens`);
const router=express.Router();
module.exports=router;