api:2.2 notice in progress 1

README.md

@@ -49,59 +49,10 @@ xdrm-framework is based on `all in config` so you will have this structure :
 
 #### 3.1 API - self-managed API
 
-###### How to use
+> version 1.0 - [documentation](/notice/api/1.0.md)
-In order to use the API, you must begin by writting your _"methods"_ in the configuration file located at `/config/modules.json`.
+> version 2.0 - [documentation](/notice/api/2.0.md)
-In order to be understood, lets call `module` a group of methods, and `method` a function which outputs data from input parameters.
+> version 2.2 - [documentation](/notice/api/2.2.md)
 
-**Configuration format**
-```json
-{
-
-	"{module_name}": {
-
-		"{http_method}::{method_name}": {
-			"description": "{method_description}",
-			"permissions": ["{method_perm}"],
-			"options": { "download": "{is_downloadable}" },
-			"parameters": {
-				"{name_param}": { "description": "{desc_param}", "type": "{type_param}", "optional": "{is_optional}" }
-			},
-			"output": {
-				"{name_output}": { "description": "{desc_output}", "type": "{type_output}" }
-			}
-		}
-
-	}
-}
-
-```
-
-|variable|description|exemple|
-|-------|-------|------|
-|`{module_name}`|alphanumeric module name|"publications"|
-|`{http_method}`|uppercase HTTP method|"POST"|
-|`{method_name}`|alphanumeric method name|"article"|
-|`{method_description}`|textual description|"Returns a specific article"|
-|`{method_perm}`|permission array|`["poster", "admin", "user"]`|
-|`{is_downloadable}`|If you want this method to return a file|`true`, `false`|
-|`{name_param}`|Your param's name|"id_article"|
-|`{desc_param}`|Your param's description|"Wanted article's id"|
-|`{type_param}`|Your param's type (cf. Checker)|"Wanted article's type"|
-|`{is_optional}`|Whether to make your param _required_|`true`, `false`|
-|`{name_output}`|Your output's name|"article"|
-|`{desc_output}`|Your output's description|"Article content"|
-
-**Implementation**
-TODO
-
-
-###### Classes (advanced)
-The API is managed through 5 classes :
-1. Request   - is the core of the module
-2. Response  - renders and manages the responses
-3. Authentification - manages the authentification part (it has to be over written for each case)
-4. Checker - manages auto checked parameters' types
-5. ModuleFactory - to instanciate each module, transparent to the user
 
 #### [3.2] error - error system
 #### [3.3] database - database wrapper and repository manager

notice/api/2.2.md

@@ -2,15 +2,142 @@
 > version: 2.2
 > requires: http:1.0, error:2.0
 
-#### I. basic knowledge
+## I. basic knowledge
 
-#### II. features
+#### 1. Types of API you can create
+The `api` can be used as a REST API because it manages HTTP methods but if you don't mind, you can use it as an only-POST api for instance.
 
 
+#### 2. Basic structure
+The api works on a 2-level delegation structure :
+
+|level|name|description
+|--|--|--|
+|1|module|Representing entity or other kind of wrapper for a set of _methods_|
+|2|method|Part of a _module_, have inputs, outputs, permissions, and is bound to a function|
 
 
-#### III. components and files
+## II. features
 
-#### IV. configuration
+* HTTP methods
+* `optional` & `required` parameters
+* parameters types auto-checker
+* multiple permissions
+* implementable Authentification (permission management)
+* `2-level` api (**module** containing **methods**)
+* not-POST (_PUT_, _PATCH_, etc) methods `multipart/form-data` parsing
+* before and after scripts
 
-#### V. implementation 
+## III. components and files
+
+## IV. How to use ?
+
+#### 1. Set up
+To make your api work, you have to:
+1. edit the configuration (mode details [here](#IV. configuration))
+2. create the modules classes and implement their methods according to your configuration (mode details [here](#V. implementation))
+
+#### 2. Internal use in php
+You can use your api from php directly without using HTTP request.
+
+First, you must require the `autoloader` file and load the API.
+
+```php
+<?php require_once '../autoloader.php'
+
+	use \api\core\Request;
+	use \api\core\Request;
+
+```
+
+Then, you must pass the module, the method and the parameters.
+
+```php
+<?php require_once '../autoloader.php'
+
+	use \api\core\Request;
+	use \api\core\Request;
+
+	$module = 'user';                        // the module 'user'
+	$method = 'getUsername';                 // and its method 'getUsername'
+	$params = ['id_user' => 'someusername']; // and the parameters
+
+	// 1. Create the request
+	$request = new Request("$module/$method", $params);
+
+	// 2. Execute request and catch response
+	$response = $request->dispatch();
+
+	// 3. Get response error code
+	$error_code = $response->error->get();
+
+	// 4. Get response output
+	$output = $response->getAll();
+
+```
+
+
+#### 3. HTTP Request use in php
+In order to setup an automatic bound from HTTP requests to API directly, you must use a router. Then you have some possibilities :
+
+**Case 1**: You want an URL like `http://www.host.com/{module}/{method}/` and pass parameters through POST or form-data. In order to set it up, you must catch the url starting at `/{module}/{method}` so you have to truncate the beginning (for instance if you have /api/{module}/..)
+
+**Case 2**: You want an URL like `http://www.host.com/api/` and pass all data through POST or form-data.
+
+## V. configuration
+
+
+###### How to use
+In order to use the API, you must begin by writting your _"methods"_ in the configuration file located at `/config/modules.json`.
+In order to be understood, lets call `module` a set of methods, and `method` a function which outputs data from input parameters.
+
+**Configuration format**
+```json
+{
+
+	"{module_name}": {
+
+		"{http_method}::{method_name}": {
+			"description": "{method_description}",
+			"permissions": ["{method_perm}"],
+			"options": { "download": "{is_downloadable}" },
+			"parameters": {
+				"{name_param}": { "description": "{desc_param}", "type": "{type_param}", "optional": "{is_optional}" }
+			},
+			"output": {
+				"{name_output}": { "description": "{desc_output}", "type": "{type_output}" }
+			}
+		}
+
+	}
+}
+
+```
+
+|variable|description|exemple|
+|-------|-------|------|
+|`{module_name}`|alphanumeric module name|"publications"|
+|`{http_method}`|uppercase HTTP method|"POST"|
+|`{method_name}`|alphanumeric method name|"article"|
+|`{method_description}`|textual description|"Returns a specific article"|
+|`{method_perm}`|permission array|`["poster", "admin", "user"]`|
+|`{is_downloadable}`|If you want this method to return a file|`true`, `false`|
+|`{name_param}`|Your param's name|"id_article"|
+|`{desc_param}`|Your param's description|"Wanted article's id"|
+|`{type_param}`|Your param's type (cf. Checker)|"Wanted article's type"|
+|`{is_optional}`|Whether to make your param _required_|`true`, `false`|
+|`{name_output}`|Your output's name|"article"|
+|`{desc_output}`|Your output's description|"Article content"|
+
+
+###### Classes (advanced)
+The API is managed through 5 classes :
+1. Request   - is the core of the module
+2. Response  - renders and manages the responses
+3. Authentification - manages the authentification part (it has to be over written for each case)
+4. Checker - manages auto checked parameters' types
+5. ModuleFactory - to instanciate each module, transparent to the user
+
+## VI. implementation
+
+For the implementation let's assume that your module is `xmodulex` and your method

src/packages/api/2.2/module/RESTexample.php

@@ -50,7 +50,11 @@ class RESTexample{
 				if(	!$success )
 					return ['error' => new Error(Err::ModuleError)]; // or other `Err` constant
 
-				return ['articles' => "Article number `$URL_0`: sometitle / somecontent"];
+				// optional param not given is set to null
+				if( is_null($URL_0) )
+					return ['articles' => [ "Article number `1`: sometitle / somecontent", "Article number `2`: sometitle / somecontent"] ];
+				else
+					return ['articles' => [ "Article number `$URL_0`: sometitle / somecontent"] ];
 				break;
 
 			case 'VIEW':