upd: notice.api:3.0 (updated for now, TODO: update links)
This commit is contained in:
xdrm-brackets
parent
7195409793
commit
a23fbce67d
|
|
@ -148,7 +148,8 @@ $specific_response_field = $response->get('specific_field_name');
|
|||
# **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..
|
||||
|
||||
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
|
||||
{
|
||||
"uri1" : {
|
||||
|
|
@ -175,6 +178,13 @@ For instance the 4 methods directly inside `uri1` will be triggered when the cal
|
|||
|
||||
"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
|
||||
|
||||
### 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**.
|
||||
Also the **namespace** must match, it corresponds to the path (starting at `/api`).
|
||||
|
||||
### Method implementation
|
||||
Each method is represented as a method in its module's class.
|
||||
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`.
|
||||
|
||||
### 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_:
|
||||
* 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
|
||||
* 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)`.
|
||||
|
||||
|
||||
|
||||
|
||||
# **V.** Class documentation
|
||||
|
||||
## **1** Request
|
||||
|
||||
### Attributes
|
||||
|
||||
The attribute `error` will contain the current `Error` instance.
|
||||
The list of available errors are set in the class `\error\core\Err`.
|
||||
|
||||
If you don't return the 'error' field, by default to
|
||||
```php
|
||||
<?php
|
||||
public $error;
|
||||
[ 'error' => new \error\core\Error(\error\core\Err::Success) ]
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
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)).
|
||||
For instance here, we manage the call `GET /article/2` where `2` is the argument `URL0` renamed to `id_article`.
|
||||
|
||||
```php
|
||||
<?php
|
||||
public function __construct(String $path, Array $params) : Request;
|
||||
use \error\core\Error;
|
||||
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).
|
||||
|
||||
```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;
|
||||
```
|
||||
*Note*: Functions `get_article_from_database()` and `has_error()` do not exist, it was in order for all to understand the example
|
||||
|
||||
|
||||
## **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.
|
||||
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`|
|
||||
|`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|
|
||||
|`hash`|`"4612473aa81f93a878..."`|String with a length of 128, 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|
|
||||
|
|
@ -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`|
|
||||
|
||||
> **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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue