150 lines
4.6 KiB
Markdown
150 lines
4.6 KiB
Markdown
> 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": {
|
|
""
|
|
}
|
|
}
|
|
|
|
}
|
|
```
|