api:2.2 notice in progress 1
This commit is contained in:
xdrm-brackets
parent
4b07a89c68
commit
9e569f861c
55
README.md
55
README.md
|
|
@ -49,59 +49,10 @@ xdrm-framework is based on `all in config` so you will have this structure :
|
|||
|
||||
#### 3.1 API - self-managed API
|
||||
|
||||
###### 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 group of methods, and `method` a function which outputs data from input parameters.
|
||||
> version 1.0 - [documentation](/notice/api/1.0.md)
|
||||
> version 2.0 - [documentation](/notice/api/2.0.md)
|
||||
> version 2.2 - [documentation](/notice/api/2.2.md)
|
||||
|
||||
**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"|
|
||||
|
||||
**Implementation**
|
||||
TODO
|
||||
|
||||
|
||||
###### 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
|
||||
|
||||
#### [3.2] error - error system
|
||||
#### [3.3] database - database wrapper and repository manager
|
||||
|
|
|
|||
|
|
@ -2,15 +2,142 @@
|
|||
> version: 2.2
|
||||
> requires: http:1.0, error:2.0
|
||||
|
||||
#### I. basic knowledge
|
||||
## I. basic knowledge
|
||||
|
||||
#### II. features
|
||||
#### 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|
|
||||
|
||||
|
||||
#### III. components and files
|
||||
## II. features
|
||||
|
||||
#### IV. configuration
|
||||
* 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
|
||||
|
||||
#### V. implementation
|
||||
## 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
|
||||
|
|
|
|||
|
|
@ -50,7 +50,11 @@ class RESTexample{
|
|||
if( !$success )
|
||||
return ['error' => new Error(Err::ModuleError)]; // or other `Err` constant
|
||||
|
||||
return ['articles' => "Article number `$URL_0`: sometitle / somecontent"];
|
||||
// optional param not given is set to null
|
||||
if( is_null($URL_0) )
|
||||
return ['articles' => [ "Article number `1`: sometitle / somecontent", "Article number `2`: sometitle / somecontent"] ];
|
||||
else
|
||||
return ['articles' => [ "Article number `$URL_0`: sometitle / somecontent"] ];
|
||||
break;
|
||||
|
||||
case 'VIEW':
|
||||
|
|
|
|||
Loading…
Reference in New Issue