291 lines
10 KiB
PHP
Executable File
291 lines
10 KiB
PHP
Executable File
<?php
|
|
|
|
namespace api\module;
|
|
use \manager\ManagerError;
|
|
|
|
class module{
|
|
|
|
/* PERMET DE TESTER L'API
|
|
*
|
|
*/
|
|
public static function method(){
|
|
|
|
return [
|
|
'ModuleError' => ManagerError::Success,
|
|
'ReceivedArguments' => func_get_args()
|
|
];
|
|
|
|
}
|
|
|
|
|
|
/* PERMET DE TESTER UNE L'ORDRE DES PARAMÈTRES
|
|
*
|
|
*/
|
|
public static function phpunitParams($params){
|
|
extract($params);
|
|
|
|
return [
|
|
'ModuleError' => ManagerError::Success,
|
|
'p1' => $p1,
|
|
'p2' => $p2
|
|
];
|
|
}
|
|
|
|
/* RENVOIE UNE DESCRIPTION EN MARKDOWN DES MODULES DE L'API
|
|
*
|
|
* @return markdown<String> 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( file_get_contents(__CONFIG__.'/modules.json'), true );
|
|
|
|
// Gestion de l'erreur de parsage
|
|
if( $modules == null )
|
|
return [ '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 [
|
|
'ModuleError' => ManagerError::Success,
|
|
'headers' => [
|
|
'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<String> 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( file_get_contents(__CONFIG__.'/modules.json'), true );
|
|
|
|
// Gestion de l'erreur de parsage
|
|
if( $modules == null )
|
|
return [ '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>`|`mixed`|Tableau contenant uniquement des données de type `mixed`|\n";
|
|
$content .= "|`array<id>`|`id`|Tableau contenant uniquement des données de type `id`|\n";
|
|
$content .= "|`array<text>`|`text`|Tableau contenant uniquement des données de type `text`|\n";
|
|
$content .= "|`array<mail>`|`mail`|Tableau contenant uniquement des données de type `mail`|\n";
|
|
$content .= "|`array<number>`|`number`|Tableau contenant uniquement des données de type `number`|\n";
|
|
$content .= "|`array<array>`|`array`|Tableau contenant uniquement des données de type `array`|\n";
|
|
$content .= "|`array<boolean>`|`boolean`|Tableau contenant uniquement des données de type `boolean`|\n";
|
|
$content .= "|`array<varchar(a,b)>`|`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<array<id>>` - Soit un tableau contenant des tableaux contenant exclusivement des données de type `id`.\n";
|
|
|
|
$content .= "\n\n\n\n\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 [
|
|
'ModuleError' => ManagerError::Success,
|
|
'headers' => [
|
|
'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
|
|
];
|
|
}
|
|
}
|
|
|
|
|
|
|
|
?>
|