updated api:2.2 notice (links)
This commit is contained in:
xdrm-brackets
parent
441ae5c810
commit
580bc54f4b
|
|
@ -9,14 +9,14 @@ requires:
|
||||||
Links
|
Links
|
||||||
====
|
====
|
||||||
|
|
||||||
[[1] User guide]()
|
[[1] User guide](#user-guide)
|
||||||
- [1 - Overview]()
|
- [1 - Overview](#1---overview)
|
||||||
- [(1) introduction & features]()
|
- [(1) introduction & features](#1-introduction--features)
|
||||||
- [(2) basic knowledge]()
|
- [(2) basic knowledge](#2-basic-knowledge)
|
||||||
- [2 - Usage]()
|
- [2 - Usage](#2---usage)
|
||||||
- [(1) setup]()
|
- [(1) setup](#1-setup)
|
||||||
- [(2) from php internally]()
|
- [(2) from php internally](#2-from-php-internally)
|
||||||
- [(3) from HTTP requests]()
|
- [(3) from HTTP requests](#3-from-http-requests)
|
||||||
- [3 - Configuration]()
|
- [3 - Configuration]()
|
||||||
- [(1) Basic usage]()
|
- [(1) Basic usage]()
|
||||||
- [(2) Advanced usage]()
|
- [(2) Advanced usage]()
|
||||||
|
|
@ -24,11 +24,11 @@ Links
|
||||||
- [(1) Permissions / AuthSystem]()
|
- [(1) Permissions / AuthSystem]()
|
||||||
- [(2) Modules & methods]()
|
- [(2) Modules & methods]()
|
||||||
- [(3) Automatic type check]()
|
- [(3) Automatic type check]()
|
||||||
- [5 - Class documentation]()
|
- [5 - Class documentation](#5---class-documentation)
|
||||||
- [(1) Request]()
|
- [(1) Request]()
|
||||||
- [(2) Response]()
|
- [(2) Response]()
|
||||||
- [(3) AuthSystem]()
|
- [(3) AuthSystem]()
|
||||||
- [(4) Checker]()
|
- [(4) Checker](#4-checker)
|
||||||
- [(4) ModuleFactory]()
|
- [(4) ModuleFactory]()
|
||||||
|
|
||||||
[[2]. Advanced guide]()
|
[[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 :
|
Things you have to do :
|
||||||
- implement your processes (obviously)
|
- implement your processes (obviously)
|
||||||
- implement your authentication system (cf. [AuthSystem]())
|
- implement your authentication system (cf. [AuthSystem](#3-authsysten))
|
||||||
- edit the configuration file (cf. [configuration]())
|
- edit the configuration file (cf. [configuration](#3---configuration))
|
||||||
|
|
||||||
Things you **don't have** to do :
|
Things you **don't have** to do :
|
||||||
- input type check (cf. [Checker]())
|
- input type check (cf. [Checker](#4-checker))
|
||||||
- API multiple permission management
|
- API multiple permission management
|
||||||
- optional or required inputs
|
- optional or required inputs
|
||||||
- before and after scripts
|
- before and after scripts
|
||||||
|
|
@ -68,8 +68,8 @@ The API is based over a 2-level delegation structure :
|
||||||
----
|
----
|
||||||
#### (1) Setup
|
#### (1) Setup
|
||||||
In order to make the API work, you have to :
|
In order to make the API work, you have to :
|
||||||
1. Edit the configuration file according to your needs (cf. [configuration]())
|
1. Edit the configuration file according to your needs (cf. [configuration](#3---configuration))
|
||||||
2. Implement the Authentication System to manage permissions (cf. [AuthSystem]())
|
2. Implement the Authentication System to manage permissions (cf. [AuthSystem](#3-authsystem))
|
||||||
|
|
||||||
|
|
||||||
#### (2) From php internally
|
#### (2) From php internally
|
||||||
|
|
@ -154,100 +154,15 @@ In order to make the API work, you have to :
|
||||||
|
|
||||||
|
|
||||||
#### (3) From HTTP requests
|
#### (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 :
|
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 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.
|
**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
|
```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"|
|
|`{name_output}`|Your output's name|"article"|
|
||||||
|`{desc_output}`|Your output's description|"Article content"|
|
|`{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>`|`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.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue