[enh] mainly space fixes

api/panel/index.php

@@ -5,7 +5,7 @@
  * you can call this HTTP(s) API as follow: 
  * from the base url https://panel.example.fr/api/
  * 1. /api/post use GETted data (?token=xx&object=xx&action=yy&option1=value1&option2=value2
- * 2. /api/post use POSTED data using the same keys 
+ * 2. /api/post use POSTED json data using the same keys 
  * 3. use a sub-url (rest-style) of the form /api/rest/object/action?token=xx&option1=value1&option2=value2
  * 4. the same (REST) but options and value are POSTED
  * 
@@ -17,19 +17,12 @@
  * Authentication is done by asking for /api/auth/<method>?option1=value1&option2=value2
  * or POSTED data
  * a token is returned for this session
- *
+ * Use /api/auth to know which method you can use and what parameter they expect
+ * @todo add HTML pages that will self-document this API
  */
-
-
 // bootstrap AlternC
 require_once("bootstrap.php");
 
-// Which api method is used ?
-define("API_CALL_GET",       1 );
-define("API_CALL_POST",      2 );
-define("API_CALL_POST_REST", 3 );
-define("API_CALL_GET_REST",  4 );
-
 /**
  * Attempts to load a class in multiple path, the PSR-0 or old style way
  * 
@@ -38,9 +31,7 @@ define("API_CALL_GET_REST",  4 );
  * @param string $class_name
  * @return boolean
  */
-
+function __autoload($class_name) {
-function __autoload($class_name)
-{
     // Contains (Namespace) => directory
     static $srcPathList = array();
     static $init = null;
@@ -67,7 +58,6 @@ function __autoload($class_name)
 
         // Sets the updated include_path
         set_include_path(implode(PATH_SEPARATOR, $finalIncludePathList));
-	
     }
 
     // Accepts old Foo_Bar namespacing
@@ -96,8 +86,7 @@ function __autoload($class_name)
     return false;
 }
 
-
+function apicall($data, $token) {
-function apicall($data,$token,$mode) {
     global $dbh;
     $options["databaseAdapter"] = $dbh;
     $options["loginAdapterList"] = array("sharedsecret", "login");
@@ -113,7 +102,6 @@ function apicall($data,$token,$mode) {
         header("Content-Type: application/json");
         echo $response->toJson();
         exit();
-
     } catch (Exception $e) {
         // something went wrong, we spit out the exception as an Api_Response
         // TODO : Don't do that on production! spit out a generic "fatal error" code and LOG the exception !
@@ -124,20 +112,16 @@ function apicall($data,$token,$mode) {
     }
 }
 
-function apiauth($data,$mode) {
+function apiauth($data) {
     global $dbh;
     $options["databaseAdapter"] = $dbh;
     // TODO (no loggerAdapter PSR3-Interface-compliant class as of now)
     try {
-
         $service = new Alternc_Api_Service($options);
-
         $response = $service->auth($data);
-
         header("Content-Type: application/json");
         echo $response->toJson();
         exit();
-
     } catch (Exception $e) {
         // something went wrong, we spit out the exception as an Api_Response
         // TODO : Don't do that on production! spit out a generic "fatal error" code and LOG the exception !
@@ -148,18 +132,22 @@ function apiauth($data,$mode) {
     }
 }
 
-
+/**
+ * Main code: either we are authenticating
+ * or calling one of the APIs 
+ * or asking for some documentation
+ */
 // Authentication 
 if (preg_match("#^/api/auth/([^/\?]*)[/\?]?#", $_SERVER["REQUEST_URI"], $mat)) {
     if ($_SERVER["REQUEST_METHOD"] == "POST") {
         $data = array("options" => $_POST,
             "method" => $mat[1]);
-    apiauth($data,API_CALL_GET);
+        apiauth($data);
         exit();
     } else {
         $data = array("options" => $_GET,
             "method" => $mat[1]);
-    apiauth($data,API_CALL_POST);
+        apiauth($data);
         exit();
     }
 }
@@ -173,7 +161,7 @@ if ($_SERVER["REQUEST_URI"]=="/api/post") {
             "action" => $_POST["action"],
         );
         $token = $_POST["token"];
-    apicall($data,$token,API_CALL_POST);
+        apicall($data, $token);
         exit();
     } else {
         $data = array("options" => $_GET,
@@ -181,7 +169,7 @@ if ($_SERVER["REQUEST_URI"]=="/api/post") {
             "action" => $_GET["action"],
         );
         $token = $_GET["token"];
-    apicall($data,$token,API_CALL_GET);
+        apicall($data, $token);
         exit();
     }
 }
@@ -192,7 +180,7 @@ if (preg_match("#^/api/rest/([^/]*)/([^/\?]*)[/\?]?#",$_SERVER["REQUEST_URI"],$m
             "action" => $mat[2]
         );
         $token = $_POST["token"];
-    apicall($data,$token,API_CALL_POST_REST);
+        apicall($data, $token);
         exit();
     } else {
         $data = array("options" => $_GET,
@@ -200,9 +188,29 @@ if (preg_match("#^/api/rest/([^/]*)/([^/\?]*)[/\?]?#",$_SERVER["REQUEST_URI"],$m
             "action" => $mat[2]
         );
         $token = $_GET["token"];
-    apicall($data,$token,API_CALL_GET_REST);
+        apicall($data, $token);
         exit();
     }
 }
 
+function doc($data) {
+    global $dbh;
+    $options["databaseAdapter"] = $dbh;
+    try {
+        $service = new Alternc_Api_Service($options);
+
+        $response = $service->documentation($data);
+        return $response;
+    } catch (Exception $e) {
+        // something went wrong, we spit out the exception as an Api_Response
+        // TODO : Don't do that on production! spit out a generic "fatal error" code and LOG the exception !
+        header("Content-Type: application/json");
+        $response = new Alternc_Api_Response(array("code" => $e->getCode(), "message" => $e->getMessage()));
+        echo $response->toJson();
+        exit();
+    }
+}
+
+doc("auth/login");
+
 echo "I did nothing. Did you call the api properly?";

lib/Alternc/Api/Auth/Interface.php

@@ -19,8 +19,8 @@ interface Alternc_Api_Auth_Interface {
     function auth($options);
 
     /**
-     * instructions on how to use this Auth class
+     * Api Documentation
      * @return array("fields" => array("fields to send, required or not"), "description" => "description of this auth")
      */
-    function instructions();
+    function documentation();
 }

lib/Alternc/Api/Auth/Login.php

@@ -1,7 +1,8 @@
 <?php
 
 /**
- * Authentication API used by server to authenticate a user using its alternc login and password
+ * Authentication API used by server to authenticate a user 
+ * using his alternc login and password
  */
 class Alternc_Api_Auth_Login implements Alternc_Api_Auth_Interface {
 
@@ -27,7 +28,7 @@ class Alternc_Api_Auth_Login implements Alternc_Api_Auth_Interface {
      * Authenticate a user
      *
      * @param $options options, depending on the auth scheme, including uid for setuid users
-     *   here, login is the alternc username, and password is the password for this username.
+     *   here, login is the AlternC username, and password is the password for this username.
      * @return an Alternc_Api_Token
      */
     function auth($options) {
@@ -56,10 +57,10 @@ class Alternc_Api_Auth_Login implements Alternc_Api_Auth_Interface {
     }
 
     /**
-     * instructions on how to use this Auth class
+     * Api Documentation
      * @return array("fields" => array("fields to send, required or not"), "description" => "description of this auth")
      */
-    function instructions() {
+    function documentation() {
         return array("fields" => array("login" => "AlternC user account", "password" => "AlternC's user password stored in membres table."),
             "description" => "Authenticate against an AlternC user and password, the same as for the control panel"
         );

lib/Alternc/Api/Auth/Sharedsecret.php

@@ -28,8 +28,6 @@ class Alternc_Api_Auth_Sharedsecret implements Alternc_Api_Auth_Interface {
         $this->db = $service->getDb();
     }
 
-// __construct
-
     /**
      * Authenticate a user
      *
@@ -67,10 +65,10 @@ class Alternc_Api_Auth_Sharedsecret implements Alternc_Api_Auth_Interface {
     }
 
     /**
-     * instructions on how to use this Auth class
+     * Api Documentation
      * @return array("fields" => array("fields to send, required or not"), "description" => "description of this auth")
      */
-    function instructions() {
+    function documentation() {
         return array("fields" => array("login" => "AlternC user account", "secret" => "API Key, Shared secrets, valid for this account, stored in sharedsecret table."),
             "description" => "Authenticate against an Api Key, also called SharedSecret. distinct from the account's password, can be plenty and revoked independently"
         );

lib/Alternc/Api/Object/Mysql.php

@@ -9,17 +9,8 @@ class Alternc_Api_Object_Mysql extends Alternc_Api_Legacyobject {
 
     function __construct($service) {
         global $mysql;
-        if (!($service instanceof Alternc_Api_Service)) {
+        parent::__construct($service);
-            throw new \Exception("Bad argument: service is not an Alternc_Api_Service", self::ERR_INVALID_ARGUMENT);
-        }
-        // We store the global $cuid to AlternC legacy classes
-        $this->cuid = $cuid = $service->token->uid;
-        $this->isAdmin = $service->token->isAdmin;
-        // We use the global $admin from AlternC legacy classes
-        $this->admin = $admin;
         $this->mysql = $mysql;
-        // Set the legacy rights:
-        $this->admin->enabled = $this->isAdmin;
     }
 
     /** API Method from legacy class method admin->add_mem()
@@ -216,4 +207,4 @@ class Alternc_Api_Object_Mysql extends Alternc_Api_Legacyobject {
 
 }
 
-// class Alternc_Api_Object_Account
+// class Alternc_Api_Object_Mysql

lib/Alternc/Api/Service.php

@@ -5,6 +5,8 @@
 
 /**
  * Service API used by server to export API methods
+ * this class can be used to implement an API service / endpoint
+ * a REST and POST api is provided as an example
  */
 class Alternc_Api_Service {
 
@@ -64,8 +66,6 @@ class Alternc_Api_Service {
         }
     }
 
-// __construct
-
     /**
      * Authenticate into an AlternC server
      * @param $auth hash with 
@@ -156,6 +156,33 @@ class Alternc_Api_Service {
         return $object->$action($request->options);
     }
 
+    /**
+     * Return documentation of the API, either general (no parameters) 
+     * or for a specific action or auth class
+     * @param string $element the name of the object for which documentation is requested
+     * @return array a documentation hash (key/value)
+     */
+    function doc($element) {
+        if (substr($element, 0, 5) == "auth/") {
+            $adapterName = "Alternc_Api_Auth_" . ucfirst(strtolower(substr($element, 5)));
+            if (!class_exists($adapterName))
+                return false;
+            $authAdapter = new $adapterName($this);
+            return $authAdapter->documentation();
+        } else {
+            list($class, $action) = explode("/", $element);
+            $className = "Alternc_Api_Object_" . ucfirst(strtolower($class));
+            if (!class_exists($className))
+                return false;
+            $object = new $className($this);
+            if (!$action) {
+                return $authAdapter->documentation();
+            } else {
+                return $authAdapter->documentation($action);
+            }
+        }
+    }
+
     /**
      * Getter for the databaseAdapter 
      * (used by authAdapter)
@@ -167,4 +194,3 @@ class Alternc_Api_Service {
 }
 
 // class Alternc_Api_Service
-