xdrm-framework/notice/api/2.2.md

```yaml
module: api
version: 2.2
requires:
  - http: 1.0
  - error: 2.0
```

Links
====

[[1] User guide](#user-guide)  
- [1 - Overview](#1---overview)  
	- [(1) introduction & features](#1-introduction--features)  
	- [(2) basic knowledge](#2-basic-knowledge)  
- [2 - Usage](#2---usage)  
	- [(1) setup](#1-setup)  
	- [(2) from php internally](#2-from-php-internally)  
	- [(3) from HTTP requests](#3-from-http-requests)  
- [3 - Configuration](#3---configuration)  
	- [(1) Basic usage](#1-basic-usage)  
	- [(2) Advanced usage](#2-advanced-usage)  
- [4 - Implementation](#4---implementation)  
	- [(1) Permissions / AuthSystem](#1-permissions-/-authsystem)
	- [(2) Modules & methods](#2-modules-&-methods)
	- [(3) Automatic type check](#3-automatic-type-check)
- [5 - Class documentation](#5---class-documentation)  
	- [(1) Request](#1-request)  
	- [(2) Response](#2-response)  
	- [(3) AuthSystem](#4-authsystem)  
	- [(4) Checker](#4-checker)  
	- [(4) ModuleFactory](#4-modulefactory)  

[[2]. Advanced guide]()  

User guide
====

1 - Overview
----

#### (1) Introduction & features
The `api` package (v2.2) allows you to easily create and manage an API. It could be an HTTP API (REST, or other), or you can use it as an internal core for your system.

The aim of this package is to make your life easier working with API. The only things you have to do is to implement your processes and edit the configuration, the package will do the rest.

Things you have to do :
- implement your processes (obviously)
- implement your authentication system (cf. [AuthSystem](#3-authsysten))
- edit the configuration file (cf. [configuration](#3---configuration))

Things you **don't have** to do :
- input type check (cf. [Checker](#4-checker))
- API multiple permission management
- optional or required inputs
- before and after scripts
- catch both in-URL and `multipart/form-data` input

#### (2) Basic knowledge

The API is based over a 2-level delegation structure :
1. `module` which is a set of methods
2. `method` which have input, output, permissions, and is bound to a function



2 - Usage
----
#### (1) Setup
In order to make the API work, you have to :
1. Edit the configuration file according to your needs (cf. [configuration](#3---configuration))
2. Implement the Authentication System to manage permissions (cf. [AuthSystem](#3-authsystem))


#### (2) Php requirements

> ##### 1) include the `autoloader` file

```php
<?php
	require_once '../autoloader.php';
```  

> ##### 2) load useful classes

```php
<?php

	...

	// for API use
	use \api\core\Request;
	use \api\core\Response;

	// for error handling
	use \error\core\Err;
```




#### (3) From php internally


> ##### 1) create a request

```php
<?php

	...

	// creates a request for the module {module} and its method {method} with params
	$request = new Request('{module}/{method}', [
		'param1' => 10,
		'param2' => 'somevalue'
	]);

```

> ##### 2) catch possible errors (optional)

```php
<?php

	...

	// if error is not Err::Success
	 if( $request->error->get() !== Err::Success )
		 'do something';
```

> ##### 3) execute the request and catch response

```php
<?php

	...

	 $response = $request->dispatch();
```

> ##### 4) catch response errors (optional)

```php
<?php

	...

	// if error is not Err::Success
	 if( $response->error->get() !== Err::Success )
		 'do something';
```

> ##### 5) catch response output

```php
<?php

	...

	// fetch all outputs
	$output = $response->getAll();

	// fetch specific output
	$specific = $response->get('someOutputName');
 ```


#### (4) From HTTP requests
In order to setup an automatic bound from HTTP requests to API directly, you must use a **router**.


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


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




5 - class documentation
----

#### (4) Checker

`Checker` checks the input values according to the type given in the configuration.

The default types below are available in the default package.
To add a new type, just open the file `/build/api/Checker.php` and add an entry in the `switch` statement.

##### Default types
|Type|Example|Description|
|---|---|---|
|`mixed`|`[9,"a"]`, `"a"`|Any content (can be simple or complex)|
|`id`|`10`, `"23"`|Positive integer number between `0` and `2147483647`|
|`numeric`|`-10.2`, `"23"`|Any number, `null` and the string `"null"`|
|`text`|`"Hello!"`|String that can be of any length (even empty)|
|`hash`|`"4612473aa81f93a878674f9ebffa8d63a1b51ea28dcdcdb1e89eb512aae9b77e"`|String with a length of 40 or 64, containing only hexadecimal characters|
|`alphanumeric`|`"abc029.-sd9"`|String containing only alphanumeric, ___, _-_, and _._ characters|
|`letters`|`"abc -sd"`|String containing only letters, _-_, and space characters|
|`mail`|`"a.b@c.def"`|Valid email address|
|`number`|`0102030405`|Phone number, following formats allowed : `06`, `+336`, `+33 6`|
|`array`|`[1, 3]`|Non-empty array|
|`object`|_works only within php_|Non-empty object|
|`boolean`|`true`, `false`|Boolean|
|`varchar(a,b)`|`"Hello!"`|String with a length between `a` and `b` (included)|
|`varchar(a,b,c)`|`"abc"`|String with a length between `a` and `b` (included) and matching the `c` type|

##### Complex type : chainable array

|Type|Sub-Type|Description|
|---|---|---|
|`array<a>`|`a`|Array containing only entries matching the type `a`|

> **Note:** It is possible to chain `array` type as many as needed.  
**Ex.:** `array<array<id>>` - Will match array only containing arrays that only contains `id` entries.