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

upd: notice.api:3.0 (updated for now, TODO: update links)

This commit is contained in:
xdrm-brackets 2017-12-12 23:51:47 +01:00
parent 7195409793
commit a23fbce67d
1 changed files with 61 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

165
notice/api/3.0.md
View File

@ -148,7 +148,8 @@ $specific_response_field = $response->get('specific_field_name');
# **III.** Configuration # **III.** Configuration
The documentation consists of a _chain_ of urls each one containing no or several HTTP method specifications. The documentation consists of a _chain_ of urls each one can contain several HTTP method specifications.
Note that each url can be chained apart the method specifications.
@ -159,6 +160,8 @@ The configuration is a set of `uri` paths that can contain up to 4 method types:
For instance the 4 methods directly inside `uri1` will be triggered when the calling URI is `/uri1`, the ones directly inside `uri2` will be triggered when calling `/uri1/uri2` and so on.. For instance the 4 methods directly inside `uri1` will be triggered when the calling URI is `/uri1`, the ones directly inside `uri2` will be triggered when calling `/uri1/uri2` and so on..
You can also set full paths if you don't need transitional methods, for instance the path `uri5/uri6/uri7` will be triggered by the url `/uri5/uri6/uri7`.
```json ```json
{ {
"uri1" : { "uri1" : {
@ -175,6 +178,13 @@ For instance the 4 methods directly inside `uri1` will be triggered when the cal
"uri3": {} "uri3": {}
} }
},
"uri5/uri6/uri7": {
"GET": method.definition,
"POST": method.definition,
"PUT": method.definition,
"DELETE": method.definition
} }
} }
``` ```
@ -286,126 +296,74 @@ For instance, lets suppose your implementation is called `myAuthSystem`.
## **2** - core implementation ## **2** - core implementation
### each path ### classes
Each module's implementation is represented as a **file** so as a **class** located in `/build/api/module/`. In order for the autoloader to work, you must name the **file** the same name as the **class**. Each module's implementation is represented as a **file** so as a **class** located in `/build/api/module/`. In order for the autoloader to work, you must name the **file** the same name as the **class**.
Also the **namespace** must match, it corresponds to the path (starting at `/api`).
### Method implementation For instance if you have in your configuration a path called `/uri1/uri2/uri3`, you will create the file `/build/api/module/uri1/uri2/uri3.php`.
Each method is represented as a method in its module's class.
### Input arguments
Arguments are passed to the method as a single argument which an associative array according to the documentation.
### methods
Each method is represented as a class' method with the same name as the associated *HTTP method*.
### method arguments
Arguments are passed to the method as a single argument which an associative array according to the configuration.
_Notes_: _Notes_:
* Optional parameters if not given are set to `null` * Optional parameters if not given are set to the `default` value given in the configuration (`null` if)
* parameters of type `FILE` are given by reference but the use is the same as normal parameters * parameters of type `FILE` are given by reference but the use is the same as normal parameters
* URL parameters are called `URL_0`, `URL_1` and so on according to their order. * URI parameters are called `URL0`, `URL1` and so on according to their order if no `rename` set in the configuration.
### Ouput required ### return statement
You must return an associative array containing at least the field `error` containing an instance of `/api/core/Error`, then you can add whatever you want to return in the array. You MUST return an associative array containing at least the field `error` containing an instance of `/api/core/Error`, then you can add whatever you want to return in the array.
If you don't return the 'error' field, by default it is set to `new Error(Err::Success)`. The list of available errors are set in the class `\error\core\Err`.
# **V.** Class documentation
## **1** Request
### Attributes
The attribute `error` will contain the current `Error` instance.
If you don't return the 'error' field, by default to
```php ```php
<?php [ 'error' => new \error\core\Error(\error\core\Err::Success) ]
public $error;
``` ```
### Methods ### example
Creates a new `Request` object, you must give it a path following the pattern "module/method", the params must be an associative array. Note that the path can be inside the `$params` variable. For instance here, we manage the call `GET /article/2` where `2` is the argument `URL0` renamed to `id_article`.
It checks missing params and each needed params' type according to the **Checker** implementation (cf. [Checker](#4-checker)). It also checks the permissions you have according to the **AuthSystem** implementation (cf. [AuthSystem](#1-permissions--authsystem)).
```php ```php
<?php use \error\core\Error;
public function __construct(String $path, Array $params) : Request; use \error\core\Err;
public function GET($parameters){
/* (1) Set parameters available in the method scope */
extract($parameters);
/* (2) You can now use the variable `id_article` */
$article_data = get_article_from_database($id_article);
/* (3) Return error if error in process */
if( has_error($article_data) )
return [ 'error' => new Error(Err::ModuleError, 'Cannot fetch data from db.') ];
/* (4) Return data on success */
return [
'id_article' => $id_article,
'article' => $article_data
];
}
``` ```
Creates a new `Request` object but from the URL. It will seek for the *path* in the URL, then in the data. (it will call itself the **\_\_construct()** method). *Note*: Functions `get_article_from_database()` and `has_error()` do not exist, it was in order for all to understand the example
```php
<?php
public static function remote(String $url, Array $data) : Request;
```
Registers the **AuthSystem** you want, must be done before any construction.
```php
<?php
public static function setAuthSystem(Request $instance) : bool;
```
Executes the current `Request` object and returns a `Response` object.
```php
<?php
public function dispatch() : Response;
```
Same as `dispatch()` but manages the **download** option (cf. [Configuration](#iii-configuration)). It will use 2 of the parameters you must return on success : `body`, and `headers`. The first one must contain the content of the file to create, the second the headers in an associative array.
The call will become the file itself.
Note: If the `HTTP_X_REQUESTED_WITH` header is present, it will create the downloadable file as **/tmp/download_{some\_hash}** and return a normal `Response` object with the field `link` containing the file absolute path.
```php
<?php
public function download() : null;
public function download() : Response; // if called by Ajax
```
## **2** Response
### Attributes
The attribute `error` will contain the current `Error` instance.
```php
<?php
public $error;
```
### Methods
Returns an associative array containing the whole response data (excluding the error).
```php
<?php
public function getAll() : Array;
```
Returns only the field from the response data (if it exists).
```php
<?php
public function get(String $key) : mixed; // on success
public function get(String $key) : null; // on error
```
Sets the `HTTP_CODE` according to the `Error` argument, also it sets the header for **application/json**.
It can be used for simple API response, it will add the *"error"* and *"ErrorDescription"* fields to the data and set the headers so you can display the result of the API call.
```php
<?php
public function serialize() : String;
```
## **4** Checker ## **3** Type Checker
`Checker` checks the input values according to the type given in the configuration. `\api\core\Checker` checks the input values according to the type given in the configuration.
The default types below are available in the default package. 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. To add a new type, just open the file `/build/api/Checker.php` and add an entry in the `switch` statement.
@ -417,11 +375,10 @@ To add a new type, just open the file `/build/api/Checker.php` and add an entry
|`id`|`10`, `"23"`|Positive integer number between `0` and `2147483647`| |`id`|`10`, `"23"`|Positive integer number between `0` and `2147483647`|
|`numeric`|`-10.2`, `"23"`|Any number, `null` and the string `"null"`| |`numeric`|`-10.2`, `"23"`|Any number, `null` and the string `"null"`|
|`text`|`"Hello!"`|String that can be of any length (even empty)| |`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| |`hash`|`"4612473aa81f93a878..."`|String with a length of 128, containing only hexadecimal characters|
|`alphanumeric`|`"abc029.-sd9"`|String containing only alphanumeric, ___, _-_, and _._ characters| |`alphanumeric`|`"abc029.-sd9"`|String containing only alphanumeric, _, _-_, and _._ characters|
|`letters`|`"abc -sd"`|String containing only letters, _-_, and space characters| |`letters`|`"abc -sd"`|String containing only letters, _-_, and space characters|
|`mail`|`"a.b@c.def"`|Valid email address| |`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| |`array`|`[1, 3]`|Non-empty array|
|`object`|_works only within php_|Non-empty object| |`object`|_works only within php_|Non-empty object|
|`boolean`|`true`, `false`|Boolean| |`boolean`|`true`, `false`|Boolean|
@ -435,10 +392,10 @@ To add a new type, just open the file `/build/api/Checker.php` and add an entry
|`array<a>`|`a`|Array containing only entries matching the type `a`| |`array<a>`|`a`|Array containing only entries matching the type `a`|
> **Note:** It is possible to chain `array` type as many as needed. > **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. **Ex.:** `array<array<id>>` - Will only match an array containing arrays that only contains `id` entries.
## **5** Advanced ## **4** Advanced
### Before and After scripts ### Before and After scripts