> 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

The API core is build over 5 classes:
> 1. **Request**        - is the core of the package
2. **Response**         - renders and manages the responses
3. **Authentification** - manages the authentification part (it has to be over written for each project)
4. **Checker**          - manages auto checked types for input parameters
5. **ModuleFactory**    - used to instanciate each module, transparent to the user

The API file structure is composed with :
> 1. the configuration file is located at `/config/modules.php`.
2. the core folder located at `/build/api/core/`
3. the module's implementation folder located at `/build/api/module/`

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

```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"|

## VI. implementation

For the implementation let's assume that `/config/modules.json` looks like this
```json
{
	"user": {
		"POST::sign_in": {
			""
		}
	}

}
```