updated api:2.2 notice (links)
This commit is contained in:
xdrm-brackets
parent
441ae5c810
commit
580bc54f4b
|
|
@ -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>`|`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
|
||||
|
||||
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>`|`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