From 92374a258ca6d3d0243f58b0b1a8f7210ee9ac95 Mon Sep 17 00:00:00 2001 From: xdrm-brackets Date: Sun, 11 Dec 2016 22:21:59 +0100 Subject: [PATCH] api:2.2 notice in progress 4 --- notice/api/2.0.md | 300 ---------------------------------------------- notice/api/2.2.md | 219 +++++++++++++++++++++++++++------ 2 files changed, 185 insertions(+), 334 deletions(-) delete mode 100644 notice/api/2.0.md diff --git a/notice/api/2.0.md b/notice/api/2.0.md deleted file mode 100644 index e3b4939..0000000 --- a/notice/api/2.0.md +++ /dev/null @@ -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 - ##### 2) load useful classes -```php - ##### 3) create a request -```php - 10, - 'param2' => 'somevalue' - ]); - -``` - -> ##### 4) catch possible errors (optional) -```php -error->get() !== Err::Success ) - 'do something'; -``` - -> ##### 5) execute the request and catch response -```php -dispatch(); -``` - -> ##### 6) catch response errors (optional) -```php -error->get() !== Err::Success ) - 'do something'; -``` - -> ##### 7) catch response output -```php -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`|Array containing only entries matching the type `a`| - -> **Note:** It is possible to chain `array` type as many as needed. -**Ex.:** `array>` - 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 - '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": { - "" - } - } - -} -``` diff --git a/notice/api/2.2.md b/notice/api/2.2.md index de13b90..e3b4939 100644 --- a/notice/api/2.2.md +++ b/notice/api/2.2.md @@ -1,46 +1,198 @@ -> module: api -> version: 2.2 -> requires: http:1.0, error:2.0 +```yaml +module: api +version: 2.2 +requires: + - http: 1.0 + - error: 2.0 +``` -## I. basic knowledge +Links +==== -#### 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. +[[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 structure -The api works on a 2-level delegation structure : +#### (2) Basic knowledge -|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| +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 -## 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 +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]()) -## 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 +#### (2) From php internally + +> ##### 1) include the `autoloader` file +```php + ##### 2) load useful classes +```php + ##### 3) create a request +```php + 10, + 'param2' => 'somevalue' + ]); + +``` + +> ##### 4) catch possible errors (optional) +```php +error->get() !== Err::Success ) + 'do something'; +``` + +> ##### 5) execute the request and catch response +```php +dispatch(); +``` + +> ##### 6) catch response errors (optional) +```php +error->get() !== Err::Success ) + 'do something'; +``` + +> ##### 7) catch response output +```php +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`|Array containing only entries matching the type `a`| + +> **Note:** It is possible to chain `array` type as many as needed. +**Ex.:** `array>` - 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 ? @@ -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. 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. @@ -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. - ```php