notice api:2.2 in progress 5

notice/api/2.2.md

@@ -17,19 +17,19 @@ Links
 	- [(1) setup](#1-setup)  
 	- [(2) from php internally](#2-from-php-internally)  
 	- [(3) from HTTP requests](#3-from-http-requests)  
-- [3 - Configuration]()  
+- [3 - Configuration](#3---configuration)  
-	- [(1) Basic usage]()  
+	- [(1) Basic usage](#1-basic-usage)  
-	- [(2) Advanced usage]()  
+	- [(2) Advanced usage](#2-advanced-usage)  
-- [4 - Implementation]()  
+- [4 - Implementation](#4---implementation)  
-	- [(1) Permissions / AuthSystem]()
+	- [(1) Permissions / AuthSystem](#1-permissions-/-authsystem)
-	- [(2) Modules & methods]()
+	- [(2) Modules & methods](#2-modules-&-methods)
-	- [(3) Automatic type check]()
+	- [(3) Automatic type check](#3-automatic-type-check)
 - [5 - Class documentation](#5---class-documentation)  
-	- [(1) Request]()  
+	- [(1) Request](#1-request)  
-	- [(2) Response]()  
+	- [(2) Response](#2-response)  
-	- [(3) AuthSystem]()  
+	- [(3) AuthSystem](#4-authsystem)  
 	- [(4) Checker](#4-checker)  
-	- [(4) ModuleFactory]()  
+	- [(4) ModuleFactory](#4-modulefactory)  
 
 [[2]. Advanced guide]()  
 
@@ -54,7 +54,7 @@ Things you **don't have** to do :
 - API multiple permission management
 - optional or required inputs
 - before and after scripts
-
+- catch both in-URL and `multipart/form-data` input
 
 #### (2) Basic knowledge
 
@@ -72,15 +72,17 @@ In order to make the API work, you have to :
 2. Implement the Authentication System to manage permissions (cf. [AuthSystem](#3-authsystem))
 
 
-#### (2) From php internally
+#### (2) Php requirements
 
 > ##### 1) include the `autoloader` file
+
 ```php
 <?php
 	require_once '../autoloader.php';
 ```  
 
 > ##### 2) load useful classes
+
 ```php
 <?php
 
@@ -94,7 +96,14 @@ In order to make the API work, you have to :
 	use \error\core\Err;
 ```
 
-> ##### 3) create a request
+
+
+
+#### (3) From php internally
+
+
+> ##### 1) create a request
+
 ```php
 <?php
 
@@ -108,7 +117,8 @@ In order to make the API work, you have to :
 
 ```
 
-> ##### 4) catch possible errors (optional)
+> ##### 2) catch possible errors (optional)
+
 ```php
 <?php
 
@@ -119,7 +129,8 @@ In order to make the API work, you have to :
 		 'do something';
 ```
 
-> ##### 5) execute the request and catch response
+> ##### 3) execute the request and catch response
+
 ```php
 <?php
 
@@ -128,7 +139,8 @@ In order to make the API work, you have to :
 	 $response = $request->dispatch();
 ```
 
-> ##### 6) catch response errors (optional)
+> ##### 4) catch response errors (optional)
+
 ```php
 <?php
 
@@ -139,7 +151,8 @@ In order to make the API work, you have to :
 		 'do something';
 ```
 
-> ##### 7) catch response output
+> ##### 5) catch response output
+
 ```php
 <?php
 
@@ -153,10 +166,60 @@ In order to make the API work, you have to :
  ```
 
 
-#### (3) From HTTP requests
+#### (4) From HTTP requests
-In order to setup an automatic bound from HTTP requests to API directly, you must use a router. Then you have some possibilities :
+In order to setup an automatic bound from HTTP requests to API directly, you must use a **router**.
 
-**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}/..)
+
+> ##### 1) Format url so it must begin with `/{module}/{method}`
+
+```php
+<?php
+	
+	...
+
+	// let's suppose the url is `/api/{module}/{method}`
+	$url = '/api/somemodule/somemethod/1/2/';
+	$url = substr($url, strlen('/api'));
+```
+
+> ##### 2) give the url to the HTTP manager
+
+```php
+<?php
+	
+	...
+	
+	// create request from HTTP data
+	$request = Request::remote($url);
+
+	// manage request error
+	if( $request->error->get() !== Err::Success )
+		die('request error');
+
+	// execute request and catch response
+	$response = $request->dispatch();
+
+	// return response as HTTP body
+	die( $response->serialize() );
+```
+
+
+
+Then can handle various kinds of URL :
+> 1. `http://www.host.com/{module}/{method}/`
+- parameters can be in URL (separated by `/`)
+- parameters can be in `multipart/form-data` or `x-www-form-urlencoded`
+- parameters of both URL and content are caught
+
+> 2. `http://www.host.com/api/{module}/{method}/`
+- parameters can be in URL (separated by `/`)
+- parameters can be in `multipart/form-data` or `x-www-form-urlencoded`
+- parameters of both URL and content are caught
+
+> 3. `http://www.host.com/`
+
+
+> 4. `https://www.host.com/api/`
 
 **Case 2**: You want an URL like `http://www.host.com/api/` and pass all data through POST or form-data.