From 580bc54f4b14bf8c830cf5a1b87e5af3bc150301 Mon Sep 17 00:00:00 2001 From: xdrm-brackets Date: Mon, 12 Dec 2016 01:16:06 +0100 Subject: [PATCH] updated api:2.2 notice (links) --- notice/api/2.2.md | 169 +++++++++++++++------------------------------- 1 file changed, 55 insertions(+), 114 deletions(-) diff --git a/notice/api/2.2.md b/notice/api/2.2.md index e3b4939..d5ce47b 100644 --- a/notice/api/2.2.md +++ b/notice/api/2.2.md @@ -9,14 +9,14 @@ requires: Links ==== -[[1] User guide]() -- [1 - Overview]() - - [(1) introduction & features]() - - [(2) basic knowledge]() -- [2 - Usage]() - - [(1) setup]() - - [(2) from php internally]() - - [(3) from HTTP requests]() +[[1] User guide](#user-guide) +- [1 - Overview](#1---overview) + - [(1) introduction & features](#1-introduction--features) + - [(2) basic knowledge](#2-basic-knowledge) +- [2 - Usage](#2---usage) + - [(1) setup](#1-setup) + - [(2) from php internally](#2-from-php-internally) + - [(3) from HTTP requests](#3-from-http-requests) - [3 - Configuration]() - [(1) Basic usage]() - [(2) Advanced usage]() @@ -24,11 +24,11 @@ Links - [(1) Permissions / AuthSystem]() - [(2) Modules & methods]() - [(3) Automatic type check]() -- [5 - Class documentation]() +- [5 - Class documentation](#5---class-documentation) - [(1) Request]() - [(2) Response]() - [(3) AuthSystem]() - - [(4) Checker]() + - [(4) Checker](#4-checker) - [(4) ModuleFactory]() [[2]. Advanced guide]() @@ -46,11 +46,11 @@ The aim of this package is to make your life easier working with API. The only t Things you have to do : - implement your processes (obviously) -- implement your authentication system (cf. [AuthSystem]()) -- edit the configuration file (cf. [configuration]()) +- implement your authentication system (cf. [AuthSystem](#3-authsysten)) +- edit the configuration file (cf. [configuration](#3---configuration)) Things you **don't have** to do : -- input type check (cf. [Checker]()) +- input type check (cf. [Checker](#4-checker)) - API multiple permission management - optional or required inputs - before and after scripts @@ -68,8 +68,8 @@ The API is based over a 2-level delegation structure : ---- #### (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]()) +1. Edit the configuration file according to your needs (cf. [configuration](#3---configuration)) +2. Implement the Authentication System to manage permissions (cf. [AuthSystem](#3-authsystem)) #### (2) From php internally @@ -154,100 +154,15 @@ In order to make the API work, you have to : #### (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 + +3 - configuration +---- ```json { @@ -285,16 +200,42 @@ In order to setup an automatic bound from HTTP requests to API directly, you mus |`{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": { - "" - } - } -} -``` + +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.