xdrm-framework/notice/api/2.2.md

150 lines
4.6 KiB
Markdown
Raw Normal View History

2016-12-11 11:05:48 +00:00
> module: api
> version: 2.2
> requires: http:1.0, error:2.0
2016-12-11 14:22:39 +00:00
## I. basic knowledge
2016-12-11 11:05:48 +00:00
2016-12-11 14:22:39 +00:00
#### 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.
2016-12-11 11:05:48 +00:00
2016-12-11 14:22:39 +00:00
#### 2. Basic structure
The api works on a 2-level delegation structure :
2016-12-11 11:05:48 +00:00
2016-12-11 14:22:39 +00:00
|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|
2016-12-11 11:05:48 +00:00
2016-12-11 14:22:39 +00:00
## II. features
2016-12-11 11:05:48 +00:00
2016-12-11 14:22:39 +00:00
* 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
2016-12-11 17:41:37 +00:00
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/`
2016-12-11 14:22:39 +00:00
## 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
2016-12-11 17:41:37 +00:00
For the implementation let's assume that `/config/modules.json` looks like this
```json
{
"user": {
"POST::sign_in": {
""
}
}
}
```