Merge pull request #33 from pxgamer/feature/api-docs

Add missing API documentation

api.php

@@ -425,8 +425,8 @@ if ($q == "getAddress") {
             api_err("Invalid destination alias");
         }
     }
-    
+
-    
+
 
     $public_key = san($data['public_key']);
     if (!$acc->valid_key($public_key)) {
@@ -456,7 +456,7 @@ if ($q == "getAddress") {
     if ($date > time() + 86400) {
         api_err("Invalid Date");
     }
-   
+
     $message=$data['message'];
     if (strlen($message) > 128) {
         api_err("The message must be less than 128 chars");
@@ -474,7 +474,7 @@ if ($q == "getAddress") {
     if ($val < 0.00000001) {
         api_err("Invalid value");
     }
-    
+
     // set alias
     if ($version==3) {
         $fee=10;
@@ -634,7 +634,7 @@ if ($q == "getAddress") {
     $public_key=san($data['public_key']);
     $signature=san($data['signature']);
     $data=$data['data'];
-    
+
     api_echo(ec_verify($data, $signature, $public_key));
 } elseif ($q == "masternodes") {
     /**
@@ -653,7 +653,7 @@ if ($q == "getAddress") {
     api_echo(["masternodes"=>$res, "hash"=>md5(json_encode($res))]);
 } elseif ($q == "getAlias") {
     /**
-     * @api {get} /api.php?q=getAlias  189. getAlias
+     * @api {get} /api.php?q=getAlias  19. getAlias
      * @apiName getAlias
      * @apiGroup API
      * @apiDescription Returns the alias of an account
@@ -664,7 +664,7 @@ if ($q == "getAddress") {
      *
      * @apiSuccess {string} data alias
      */
-    
+
     $public_key = $data['public_key'];
     $account = $data['account'];
     if (!empty($public_key) && strlen($public_key) < 32) {
@@ -673,30 +673,62 @@ if ($q == "getAddress") {
     if (!empty($public_key)) {
         $account = $acc->get_address($public_key);
     }
-  
+
     if (empty($account)) {
         api_err("Invalid account id");
     }
     $account = san($account);
-    
+
     api_echo($acc->account2alias($account));
-} elseif ($q=="sanity"){
+} elseif ($q === 'sanity') {
-    $sanity=false;
+    /**
-    if(file_exists("tmp/sanity-lock")) {
+     * @api            {get} /api.php?q=sanity  20. sanity
-        $sanity=true;
+     * @apiName        sanity
-    }    
+     * @apiGroup       API
-    $last_sanity=$db->single("SELECT val FROM config WHERE cfg='sanity_last'");
+     * @apiDescription Returns details about the node's sanity process.
-    $sanity_sync=$db->single("SELECT val FROM config WHERE cfg='sanity_sync'");
+     *
-    api_echo(["sanity_running"=>$sanity,"last_sanity"=>$last_sanity, "sanity_sync"=>$sanity_sync]);
+     * @apiSuccess {object}  data A collection of data about the sanity process.
-} elseif ($q=="node-info"){
+     * @apiSuccess {boolean} data.sanity_running Whether the sanity process is currently running.
-    $dbversion=$db->single("SELECT val FROM config WHERE cfg='dbversion'");
+     * @apiSuccess {number}  data.last_sanity The timestamp for the last time the sanity process was run.
-    $hostname=$db->single("SELECT val FROM config WHERE cfg='hostname'");
+     * @apiSuccess {boolean} data.sanity_sync Whether the sanity process is currently synchronising.
-    $acc=$db->single("SELECT COUNT(1) FROM accounts");
+     */
-    $tr=$db->single("SELECT COUNT(1) FROM transactions");
+    $sanity = file_exists(__DIR__.'/tmp/sanity-lock');
-    $mns=$db->single("SELECT COUNT(1) FROM masternode");
+
-    $mempool=$db->single("SELECT COUNT(1) FROM mempool");
+    $lastSanity = (int)$db->single("SELECT val FROM config WHERE cfg='sanity_last'");
-    api_echo(["hostname"=>$hostname, "version"=>VERSION,"dbversion"=>$dbversion, "accounts"=>$acc, "transactions"=>$tr, "mempool"=>$mempool, "masternodes"=>$mns]);
+    $sanitySync = (bool)$db->single("SELECT val FROM config WHERE cfg='sanity_sync'");
-    
+    api_echo(['sanity_running' => $sanity, 'last_sanity' => $lastSanity, 'sanity_sync' => $sanitySync]);
+} elseif ($q === 'node-info') {
+    /**
+     * @api            {get} /api.php?q=node-info  21. node-info
+     * @apiName        node-info
+     * @apiGroup       API
+     * @apiDescription Returns details about the node.
+     *
+     * @apiSuccess {object}  data A collection of data about the node.
+     * @apiSuccess {string} data.hostname The hostname of the node.
+     * @apiSuccess {string} data.version The current version of the node.
+     * @apiSuccess {string} data.dbversion The database schema version for the node.
+     * @apiSuccess {number} data.accounts The number of accounts known by the node.
+     * @apiSuccess {number} data.transactions The number of transactions known by the node.
+     * @apiSuccess {number} data.mempool The number of transactions in the mempool.
+     * @apiSuccess {number} data.masternodes The number of masternodes known by the node.
+     */
+    $dbVersion = $db->single("SELECT val FROM config WHERE cfg='dbversion'");
+    $hostname = $db->single("SELECT val FROM config WHERE cfg='hostname'");
+    $acc = $db->single("SELECT COUNT(1) FROM accounts");
+    $tr = $db->single("SELECT COUNT(1) FROM transactions");
+    $masternodes = $db->single("SELECT COUNT(1) FROM masternode");
+    $mempool = $db->single("SELECT COUNT(1) FROM mempool");
+
+    api_echo([
+        'hostname'     => $hostname,
+        'version'      => VERSION,
+        'dbversion'    => $dbVersion,
+        'accounts'     => $acc,
+        'transactions' => $tr,
+        'mempool'      => $mempool,
+        'masternodes'  => $masternodes,
+    ]);
 } else {
     api_err("Invalid request");
 }

doc/api_data.js

@@ -303,7 +303,7 @@ define({ "api": [
   {
     "type": "get",
     "url": "/api.php?q=getAlias",
-    "title": "189. getAlias",
+    "title": "19. getAlias",
     "name": "getAlias",
     "group": "API",
     "description": "<p>Returns the alias of an account</p>",
@@ -1015,6 +1015,79 @@ define({ "api": [
     "filename": "./api.php",
     "groupTitle": "API"
   },
+  {
+    "type": "get",
+    "url": "/api.php?q=node-info",
+    "title": "21. node-info",
+    "name": "node_info",
+    "group": "API",
+    "description": "<p>Returns details about the node.</p>",
+    "success": {
+      "fields": {
+        "Success 200": [
+          {
+            "group": "Success 200",
+            "type": "object",
+            "optional": false,
+            "field": "data",
+            "description": "<p>A collection of data about the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "string",
+            "optional": false,
+            "field": "data.hostname",
+            "description": "<p>The hostname of the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "string",
+            "optional": false,
+            "field": "data.version",
+            "description": "<p>The current version of the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "string",
+            "optional": false,
+            "field": "data.dbversion",
+            "description": "<p>The database schema version for the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.accounts",
+            "description": "<p>The number of accounts known by the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.transactions",
+            "description": "<p>The number of transactions known by the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.mempool",
+            "description": "<p>The number of transactions in the mempool.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.masternodes",
+            "description": "<p>The number of masternodes known by the node.</p>"
+          }
+        ]
+      }
+    },
+    "version": "0.0.0",
+    "filename": "./api.php",
+    "groupTitle": "API"
+  },
   {
     "type": "get",
     "url": "/api.php?q=randomNumber",
@@ -1073,6 +1146,51 @@ define({ "api": [
     "filename": "./api.php",
     "groupTitle": "API"
   },
+  {
+    "type": "get",
+    "url": "/api.php?q=sanity",
+    "title": "20. sanity",
+    "name": "sanity",
+    "group": "API",
+    "description": "<p>Returns details about the node's sanity process.</p>",
+    "success": {
+      "fields": {
+        "Success 200": [
+          {
+            "group": "Success 200",
+            "type": "object",
+            "optional": false,
+            "field": "data",
+            "description": "<p>A collection of data about the sanity process.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "boolean",
+            "optional": false,
+            "field": "data.sanity_running",
+            "description": "<p>Whether the sanity process is currently running.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.last_sanity",
+            "description": "<p>The timestamp for the last time the sanity process was run.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "boolean",
+            "optional": false,
+            "field": "data.sanity_sync",
+            "description": "<p>Whether the sanity process is currently synchronising.</p>"
+          }
+        ]
+      }
+    },
+    "version": "0.0.0",
+    "filename": "./api.php",
+    "groupTitle": "API"
+  },
   {
     "type": "get",
     "url": "/api.php?q=send",
@@ -1183,6 +1301,34 @@ define({ "api": [
     "filename": "./api.php",
     "groupTitle": "API"
   },
+  {
+    "success": {
+      "fields": {
+        "Success 200": [
+          {
+            "group": "Success 200",
+            "optional": false,
+            "field": "varname1",
+            "description": "<p>No type.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "String",
+            "optional": false,
+            "field": "varname2",
+            "description": "<p>With type.</p>"
+          }
+        ]
+      }
+    },
+    "type": "",
+    "url": "",
+    "version": "0.0.0",
+    "filename": "./doc/main.js",
+    "group": "C__Users_owen_voke_Documents_GitHub_php_arionum_node_doc_main_js",
+    "groupTitle": "C__Users_owen_voke_Documents_GitHub_php_arionum_node_doc_main_js",
+    "name": ""
+  },
   {
     "type": "php util.php",
     "url": "balance",
@@ -1689,33 +1835,5 @@ define({ "api": [
     "version": "0.0.0",
     "filename": "./util.php",
     "groupTitle": "UTIL"
-  },
-  {
-    "success": {
-      "fields": {
-        "Success 200": [
-          {
-            "group": "Success 200",
-            "optional": false,
-            "field": "varname1",
-            "description": "<p>No type.</p>"
-          },
-          {
-            "group": "Success 200",
-            "type": "String",
-            "optional": false,
-            "field": "varname2",
-            "description": "<p>With type.</p>"
-          }
-        ]
-      }
-    },
-    "type": "",
-    "url": "",
-    "version": "0.0.0",
-    "filename": "./doc/main.js",
-    "group": "_github_node_doc_main_js",
-    "groupTitle": "_github_node_doc_main_js",
-    "name": ""
   }
 ] });

doc/api_data.json

@@ -303,7 +303,7 @@
   {
     "type": "get",
     "url": "/api.php?q=getAlias",
-    "title": "189. getAlias",
+    "title": "19. getAlias",
     "name": "getAlias",
     "group": "API",
     "description": "<p>Returns the alias of an account</p>",
@@ -1015,6 +1015,79 @@
     "filename": "./api.php",
     "groupTitle": "API"
   },
+  {
+    "type": "get",
+    "url": "/api.php?q=node-info",
+    "title": "21. node-info",
+    "name": "node_info",
+    "group": "API",
+    "description": "<p>Returns details about the node.</p>",
+    "success": {
+      "fields": {
+        "Success 200": [
+          {
+            "group": "Success 200",
+            "type": "object",
+            "optional": false,
+            "field": "data",
+            "description": "<p>A collection of data about the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "string",
+            "optional": false,
+            "field": "data.hostname",
+            "description": "<p>The hostname of the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "string",
+            "optional": false,
+            "field": "data.version",
+            "description": "<p>The current version of the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "string",
+            "optional": false,
+            "field": "data.dbversion",
+            "description": "<p>The database schema version for the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.accounts",
+            "description": "<p>The number of accounts known by the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.transactions",
+            "description": "<p>The number of transactions known by the node.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.mempool",
+            "description": "<p>The number of transactions in the mempool.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.masternodes",
+            "description": "<p>The number of masternodes known by the node.</p>"
+          }
+        ]
+      }
+    },
+    "version": "0.0.0",
+    "filename": "./api.php",
+    "groupTitle": "API"
+  },
   {
     "type": "get",
     "url": "/api.php?q=randomNumber",
@@ -1073,6 +1146,51 @@
     "filename": "./api.php",
     "groupTitle": "API"
   },
+  {
+    "type": "get",
+    "url": "/api.php?q=sanity",
+    "title": "20. sanity",
+    "name": "sanity",
+    "group": "API",
+    "description": "<p>Returns details about the node's sanity process.</p>",
+    "success": {
+      "fields": {
+        "Success 200": [
+          {
+            "group": "Success 200",
+            "type": "object",
+            "optional": false,
+            "field": "data",
+            "description": "<p>A collection of data about the sanity process.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "boolean",
+            "optional": false,
+            "field": "data.sanity_running",
+            "description": "<p>Whether the sanity process is currently running.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "number",
+            "optional": false,
+            "field": "data.last_sanity",
+            "description": "<p>The timestamp for the last time the sanity process was run.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "boolean",
+            "optional": false,
+            "field": "data.sanity_sync",
+            "description": "<p>Whether the sanity process is currently synchronising.</p>"
+          }
+        ]
+      }
+    },
+    "version": "0.0.0",
+    "filename": "./api.php",
+    "groupTitle": "API"
+  },
   {
     "type": "get",
     "url": "/api.php?q=send",
@@ -1183,6 +1301,34 @@
     "filename": "./api.php",
     "groupTitle": "API"
   },
+  {
+    "success": {
+      "fields": {
+        "Success 200": [
+          {
+            "group": "Success 200",
+            "optional": false,
+            "field": "varname1",
+            "description": "<p>No type.</p>"
+          },
+          {
+            "group": "Success 200",
+            "type": "String",
+            "optional": false,
+            "field": "varname2",
+            "description": "<p>With type.</p>"
+          }
+        ]
+      }
+    },
+    "type": "",
+    "url": "",
+    "version": "0.0.0",
+    "filename": "./doc/main.js",
+    "group": "C__Users_owen_voke_Documents_GitHub_php_arionum_node_doc_main_js",
+    "groupTitle": "C__Users_owen_voke_Documents_GitHub_php_arionum_node_doc_main_js",
+    "name": ""
+  },
   {
     "type": "php util.php",
     "url": "balance",
@@ -1689,33 +1835,5 @@
     "version": "0.0.0",
     "filename": "./util.php",
     "groupTitle": "UTIL"
-  },
-  {
-    "success": {
-      "fields": {
-        "Success 200": [
-          {
-            "group": "Success 200",
-            "optional": false,
-            "field": "varname1",
-            "description": "<p>No type.</p>"
-          },
-          {
-            "group": "Success 200",
-            "type": "String",
-            "optional": false,
-            "field": "varname2",
-            "description": "<p>With type.</p>"
-          }
-        ]
-      }
-    },
-    "type": "",
-    "url": "",
-    "version": "0.0.0",
-    "filename": "./doc/main.js",
-    "group": "_github_node_doc_main_js",
-    "groupTitle": "_github_node_doc_main_js",
-    "name": ""
   }
 ]

doc/api_project.js

@@ -1,13 +1,14 @@
 define({
-  "name": "",
+  "name": "Arionum Node",
   "version": "0.0.0",
-  "description": "",
+  "description": "The Arionum Node API and utility documentation.",
+  "title": "Arionum Node",
   "sampleUrl": false,
   "defaultVersion": "0.0.0",
   "apidoc": "0.3.0",
   "generator": {
     "name": "apidoc",
-    "time": "2018-08-05T21:17:14.214Z",
+    "time": "2018-10-12T11:08:47.065Z",
     "url": "http://apidocjs.com",
     "version": "0.17.6"
   }

doc/api_project.json

@@ -1,13 +1,14 @@
 {
-  "name": "",
+  "name": "Arionum Node",
   "version": "0.0.0",
-  "description": "",
+  "description": "The Arionum Node API and utility documentation.",
+  "title": "Arionum Node",
   "sampleUrl": false,
   "defaultVersion": "0.0.0",
   "apidoc": "0.3.0",
   "generator": {
     "name": "apidoc",
-    "time": "2018-08-05T21:17:14.214Z",
+    "time": "2018-10-12T11:08:47.065Z",
     "url": "http://apidocjs.com",
     "version": "0.17.6"
   }