ManagerError::Success, 'ReceivedArguments' => func_get_args() ); } /* PERMET DE TESTER UNE L'ORDRE DES PARAMÈTRES * */ public static function phpunitParams($params){ extract($params); return array( 'ModuleError' => ManagerError::Success, 'p1' => $p1, 'p2' => $p2 ); } /* RENVOIE UNE DESCRIPTION EN MARKDOWN DES MODULES DE L'API * * @return markdown Description des modules * */ public static function markdown(){ /* [1] Récupération de la configuration =========================================================*/ // On récupère le fichier et on le parse $modules = json_decode( ResourceDispatcher::getResource('f/json/modules/conf'), true ); // Gestion de l'erreur de parsage if( $modules == null ) return array( 'ModuleError' => ManagerError::ParsingFailed ); /* [2] Mise en forme de la liste des modules =========================================================*/ $markdown = "## Module List\n"; foreach($modules as $moduleName=>$moduleData) $markdown .= "- $moduleName\n"; /* [3] Mise en forme des méthodes des modules =========================================================*/ $markdown .= "----\n## Method List & Description\n"; $count = 1; foreach($modules as $moduleName=>$moduleData){ $markdown .= "### $count - '$moduleName' methods\n"; foreach($moduleData as $methodName=>$methodData) $markdown .= "`$methodName` - ".$methodData['description']."\n"; $markdown .= "----\n"; $count++; } /* [n] Gestion du retour =========================================================*/ return array( 'ModuleError' => ManagerError::Success, 'headers' => array( 'Content-Type' => 'text/markdown; charset=utf-8', 'Content-Transfer-Encoding' => 'binary', 'Content-Disposition' => 'attachment; filename=NxTIC.apib', 'Pragma' => 'no-cache', 'Expires' => '0' ), 'body' => $markdown ); } /* RENVOIE UNE DOC API_BLUEPRINT DE L'API * * @return apiBlueprint Description des modules au format API Blueprint * */ public static function apiBlueprint(){ /* [0] Récupération de la configuration =========================================================*/ // On récupère le fichier et on le parse $modules = json_decode( ResourceDispatcher::getResource('f/json/modules/conf'), true ); // Gestion de l'erreur de parsage if( $modules == null ) return array( 'ModuleError' => ManagerError::ParsingFailed ); /* [1] Début du fichier custom =========================================================*/ $content = "FORMAT: 1A\n"; $content .= "HOST: https://socioview.xdrm.io/api/\n\n"; $content .= "# NxTIC API\n"; $content .= "API de la plateforme d'étude **NxTIC**, cette documentation présentera toutes les méthodes accessibles depuis la plateforme elle-même et depuis un logiciel tiers.\n"; $content .= "La plateforme **NxTIC** est une plateforme d'étude sociale développé par Adrien Marquès _(xdrm-brackets)_ pour un laboratoire de sociologie du _CNRS_.\n"; $content .= "Elle a pour objectif l'acquisition, la visualisation et l'extraction de données relationnelles.\n"; $content .= "> Cette plateforme est temporairement hébergée sur https://socioview.xdrm.io/.\n\n"; $content .= "## Structure et fonctionnement\n"; $content .= "Le fonctionnement est basé sur une délégation à 2 niveaux : des __modules__ contenant des __méthodes__.\n\n"; $content .= "***\n\n"; $content .= "### Paramètres\n"; $content .= "Tous les paramètres doivent être envoyés en `multipart/form-data`.\n\n"; $content .= "1. Chacun formatté en `json` \n"; $content .= "2. Portant le `nom` défini dans la documentation \n"; $content .= "3. L'ordre n'a pas d'importance \n"; $content .= "4. Respectant le `type` défini dans la documentation (cf. [Types](#introduction/types-de-donnees)) \n\n"; $content .= "> **Note:** Les `paramètres URI` ne correspondent pas aux paramètres URI. \n"; $content .= "Ils servent à expliciter les paramètres et leurs types, et correspondent aux variables notées `{nomVar}` dans le corps de la requête.\n\n"; $content .= "### Réponses\n\n"; $content .= "#### A. Les réponses seront formattées en json et contiendront:\n\n"; $content .= "1. `ModuleError` - Le code de l'erreur \n"; $content .= "2. `ErrorDescription` - La description de l'erreur\n\n"; $content .= "****\n\n"; $content .= "#### B. Codes `HTTP` et leur signification.\n\n"; $content .= "|Status|Code HTTP|\n"; $content .= "|---|---|\n"; $content .= "|OK|`200` - Success|\n"; $content .= "|Erreur|`417` - Erreur quelconque|\n\n"; $content .= "## Types de données\n\n"; $content .= "### Types Simples \n"; $content .= "|Type|Exemple|Description|\n"; $content .= "|---|---|---|\n"; $content .= "|`mixed`|`[9,\"a\"]`, `\"a\"`|Type quelconque (peut être simple ou composé)|\n"; $content .= "|`id`|`10`, `\"23\"`|Nombre entier positif compris entre `0` et `2147483647`|\n"; $content .= "|`text`|`\"Hello!\"`|Chaine de caractères de longueur quelconque (peut être vide)|\n"; $content .= "|`mail`|`\"a.b@c.def\"`|Adresse mail avec une syntaxe valide|\n"; $content .= "|`number`|`0102030405`|Numéro de téléphone valide suivant les formats : `06`, `+336`, `+33 6`|\n"; $content .= "|`array`|`[1, 3]`|Tableau quelconque non vide|\n"; $content .= "|`boolean`|`true`, `false`|Booléen|\n"; $content .= "|`varchar(a,b)`|`\"Hello!\"`|Chaine de caractères de taille comprise entre `a` et `b` (inclus)|\n\n"; $content .= "### Type composé : array\n\n"; $content .= "|Type|Sous-Type|Description|\n"; $content .= "|---|---|---|\n"; $content .= "|`array`|`mixed`|Tableau contenant uniquement des données de type `mixed`|\n"; $content .= "|`array`|`id`|Tableau contenant uniquement des données de type `id`|\n"; $content .= "|`array`|`text`|Tableau contenant uniquement des données de type `text`|\n"; $content .= "|`array`|`mail`|Tableau contenant uniquement des données de type `mail`|\n"; $content .= "|`array`|`number`|Tableau contenant uniquement des données de type `number`|\n"; $content .= "|`array`|`array`|Tableau contenant uniquement des données de type `array`|\n"; $content .= "|`array`|`boolean`|Tableau contenant uniquement des données de type `boolean`|\n"; $content .= "|`array`|`varchar(a,b)`|Tableau contenant uniquement des données de type `varchar(a,b)`|\n\n"; $content .= "> **Note:** Il est possible de chainer le type `array` autant de fois que nécessaire. \n"; $content .= "**Ex.:** `array>` - Soit un tableau contenant des tableaux contenant exclusivement des données de type `id`.\n"; /* [2] Pour chaque module =========================================================*/ foreach($modules as $module=>$methods){ $content .= "## $module [/$module] \n\n"; /* [3] Pour chaque méthode =========================================================*/ foreach($methods as $methName=>$method){ /* (1) Description */ $content .= "### $methName [POST /$module/$methName]\n\n"; $content .= $method['description']."\n"; if( count($method['permissions']) > 0) $content .= '> Permissions `'.implode('``', $method['permissions'])."`\n\n"; // Liste des paramètres if( isset($method['parameters']) && count($method['parameters']) > 0 ){ // On explicite tous les paramètres $content .= "+ Parameters\n\n"; foreach($method['parameters'] as $argName=>$argument){ $optional = isset($argument['optional']) && $argument['optional'] === true; $content .= " + $argName (${argument['type']}, ".( $optional ? 'optional' : 'required' ).") - ${argument['description']}\n"; } $content .= "\n"; } /* (2) Requête */ $content .= "+ Request (multipart/form-data; boundary=xxxBOUNDARYxxx)\n\n"; // Header $content .= " + Headers\n\n"; $content .= " Authorization: Digest {yourAccessToken}\n"; $content .= " Cache-Control: no-cache\n"; if( isset($method['parameters']) && count($method['parameters']) > 0 ){ // Body $content .= " + Body\n\n"; foreach($method['parameters'] as $argName=>$argument){ $content .= " --xxxBOUNDARYxxx\n"; $content .= " Content-Disposition: form-data; name=\"$argName\"\n"; $content .= " Content-Type: application/json\n\n"; $content .= " {".$argName."}\n"; } $content .= " --xxxBOUNDARYxxx--\n"; // Schema $content .= " + Schema\n\n"; $content .= " {\n"; foreach($method['parameters'] as $argName=>$argData) $content .= " \"$argName\": @$argName\n"; $content .= " }\n"; } /* (3) Réponse */ $content .= "\n+ Response 200 (application/json)\n\n"; if( isset($method['output']) && count($method['output']) > 0 ){ // Body $content .= " + Body\n\n"; $content .= " {\n"; foreach($method['output'] as $outName=>$outData) $content .= " \"$outName\": @$outName\n"; $content .= " }\n"; // Schema $content .= " + Schema\n\n"; $content .= " {\n"; foreach($method['output'] as $outName=>$outData) $content .= " \"$outName\": @$outName\n"; $content .= " }\n"; // On explicite tous les paramètres $content .= " + Attributes (object)\n\n"; foreach($method['output'] as $outName=>$outData) $content .= " + $outName (${outData['type']}) - ${outData['description']}\n"; } $content .= "\n\n"; } } return array( 'ModuleError' => ManagerError::Success, 'headers' => array( 'Content-Type' => 'application/octet-stream; charset=utf-8', 'Content-Transfer-Encoding' => 'binary', 'Content-Disposition' => 'attachment; filename=NxTIC.apib', 'Pragma' => 'no-cache', 'Expires' => '0' ), 'body' => $content ); } } ?>