xdrm-brackets
/
xdrm-framework
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

api:2.2 notice in progress 4

This commit is contained in:
xdrm-brackets 2016-12-11 22:21:59 +01:00
parent 4bccd21c2e
commit 92374a258c
2 changed files with 185 additions and 334 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

300
notice/api/2.0.md
View File

@ -1,300 +0,0 @@
```yaml
module: api
version: 2.2
requires:
- http: 1.0
- error: 2.0
```
Links
====
[[1] User guide]()
- [1 - Overview]()
- [(1) introduction & features]()
- [(2) basic knowledge]()
- [2 - Usage]()
- [(1) setup]()
- [(2) from php internally]()
- [(3) from HTTP requests]()
- [3 - Configuration]()
- [(1) Basic usage]()
- [(2) Advanced usage]()
- [4 - Implementation]()
- [(1) Permissions / AuthSystem]()
- [(2) Modules & methods]()
- [(3) Automatic type check]()
- [5 - Class documentation]()
- [(1) Request]()
- [(2) Response]()
- [(3) AuthSystem]()
- [(4) Checker]()
- [(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]())
- edit the configuration file (cf. [configuration]())
Things you **don't have** to do :
- input type check (cf. [Checker]())
- API multiple permission management
- optional or required inputs
- before and after scripts
#### (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]())
2. Implement the Authentication System to manage permissions (cf. [AuthSystem]())
#### (2) From php internally
> ##### 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) 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'
]);
```
> ##### 4) catch possible errors (optional)
```php
<?php
...
// if error is not Err::Success
if( $request->error->get() !== Err::Success )
'do something';
```
> ##### 5) execute the request and catch response
```php
<?php
...
$response = $request->dispatch();
```
> ##### 6) catch response errors (optional)
```php
<?php
...
// if error is not Err::Success
if( $response->error->get() !== Err::Success )
'do something';
```
> ##### 7) catch response output
```php
<?php
...
// fetch all outputs
$output = $response->getAll();
// fetch specific output
$specific = $response->get('someOutputName');
```
#### (3) From HTTP requests
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.
## 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 internally 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": {
""
}
}
}
```

219
notice/api/2.2.md
View File

@ -1,46 +1,198 @@
> module: api ```yaml
> version: 2.2 module: api
> requires: http:1.0, error:2.0 version: 2.2
requires:
- http: 1.0
- error: 2.0
```
## I. basic knowledge Links
====
#### 1. Types of API you can create [[1] User guide]()
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. - [1 - Overview]()
- [(1) introduction & features]()
- [(2) basic knowledge]()
- [2 - Usage]()
- [(1) setup]()
- [(2) from php internally]()
- [(3) from HTTP requests]()
- [3 - Configuration]()
- [(1) Basic usage]()
- [(2) Advanced usage]()
- [4 - Implementation]()
- [(1) Permissions / AuthSystem]()
- [(2) Modules & methods]()
- [(3) Automatic type check]()
- [5 - Class documentation]()
- [(1) Request]()
- [(2) Response]()
- [(3) AuthSystem]()
- [(4) Checker]()
- [(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]())
- edit the configuration file (cf. [configuration]())
Things you **don't have** to do :
- input type check (cf. [Checker]())
- API multiple permission management
- optional or required inputs
- before and after scripts
#### 2. Basic structure #### (2) Basic knowledge
The api works on a 2-level delegation structure :
|level|name|description The API is based over a 2-level delegation structure :
|--|--|--| 1. `module` which is a set of methods
|1|module|Representing entity or other kind of wrapper for a set of _methods_| 2. `method` which have input, output, permissions, and is bound to a function
|2|method|Part of a _module_, have inputs, outputs, permissions, and is bound to a function|
## II. features
* HTTP methods 2 - Usage
* `optional` & `required` parameters ----
* parameters types auto-checker #### (1) Setup
* multiple permissions In order to make the API work, you have to :
* implementable Authentification (permission management) 1. Edit the configuration file according to your needs (cf. [configuration]())
* `2-level` api (**module** containing **methods**) 2. Implement the Authentication System to manage permissions (cf. [AuthSystem]())
* 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: #### (2) From php internally
> 1. **Request** - is the core of the package
2. **Response** - renders and manages the responses > ##### 1) include the `autoloader` file
3. **Authentification** - manages the authentification part (it has to be over written for each project) ```php
4. **Checker** - manages auto checked types for input parameters <?php
5. **ModuleFactory** - used to instanciate each module, transparent to the user 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) 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'
]);
```
> ##### 4) catch possible errors (optional)
```php
<?php
...
// if error is not Err::Success
if( $request->error->get() !== Err::Success )
'do something';
```
> ##### 5) execute the request and catch response
```php
<?php
...
$response = $request->dispatch();
```
> ##### 6) catch response errors (optional)
```php
<?php
...
// if error is not Err::Success
if( $response->error->get() !== Err::Success )
'do something';
```
> ##### 7) catch response output
```php
<?php
...
// fetch all outputs
$output = $response->getAll();
// fetch specific output
$specific = $response->get('someOutputName');
```
#### (3) From HTTP requests
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.
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 ? ## IV. How to use ?
@ -50,7 +202,7 @@ To make your api work, you have to:
2. create the modules classes and implement their methods according to your configuration (mode details [here](#V. implementation)) 2. create the modules classes and implement their methods according to your configuration (mode details [here](#V. implementation))
#### 2. Internal use in php #### 2. Internal use in php
You can use your api from php directly without using HTTP request. You can use your api from php internally without using HTTP request.
First, you must require the `autoloader` file and load the API. First, you must require the `autoloader` file and load the API.
@ -63,7 +215,6 @@ First, you must require the `autoloader` file and load the API.
``` ```
Then, you must pass the module, the method and the parameters. Then, you must pass the module, the method and the parameters.
```php ```php
<?php require_once '../autoloader.php' <?php require_once '../autoloader.php'