xdrm-framework/notice/api/2.2.md

> module: api
> version: 2.2
> requires: http:1.0, error:2.0

## I. basic knowledge

#### 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|


## II. features

* 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

## 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