api:2.2 documentation update
This commit is contained in:
xdrm-brackets
parent
2d189b7bae
commit
7467b15664
|
|
@ -53,14 +53,16 @@ xdrm-framework is based on `all in config` so you will have this structure :
|
|||
#### 3.1 API - self-managed API
|
||||
|
||||
> version 1.0 - [documentation](/notice/api/1.0.md)
|
||||
|
||||
> version 2.0 - [documentation](/notice/api/2.0.md)
|
||||
|
||||
> version 2.2 - [documentation](/notice/api/2.2.md)
|
||||
|
||||
#### 3.2 Log - multilog system
|
||||
|
||||
> version 1.0 - [documentation](/notice/log/1.0.md)
|
||||
|
||||
#### 3.3 Log - optimized file driver
|
||||
#### 3.3 Filedriver - optimized file driver
|
||||
|
||||
> version 1.0 - [documentation](/notice/filedriver/1.0.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ Links
|
|||
- [(1) Basic usage](#1-basic-usage)
|
||||
- [(2) Advanced usage](#2-advanced-usage)
|
||||
- [4 - Implementation](#4---implementation)
|
||||
- [(1) Permissions / AuthSystem](#1-permissions-/-authsystem)
|
||||
- [(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)
|
||||
|
|
@ -40,10 +40,10 @@ User guide
|
|||
1 - Overview
|
||||
----
|
||||
|
||||
#### (1) Introduction & features
|
||||
The `api` package (v2.2) allows you to easily create and manage an API. It could be an HTTP API (REST, or other), or you can use it as an internal core for your system.
|
||||
## (1) Introduction & features
|
||||
The `api` package (v2.2) allows you to easily create and manage an API. It could be used for an HTTP API (REST, or other kind), or you can use it as an internal core for your system.
|
||||
|
||||
The aim of this package is to make your life easier working with API. The only things you have to do is to implement your processes and edit the configuration, the package will do the rest.
|
||||
The aim of this package is to make your life easier working with APIs or internal delegation. The only things you have to do is to implement your processes and edit the configuration, the package will do the rest.
|
||||
|
||||
Things you have to do :
|
||||
- implement your processes (obviously)
|
||||
|
|
@ -57,38 +57,43 @@ Things you **don't have** to do :
|
|||
- before and after scripts
|
||||
- catch both in-URL and `multipart/form-data` input
|
||||
|
||||
#### (2) Basic knowledge
|
||||
## (2) Basic knowledge
|
||||
|
||||
The API is based over a 2-level delegation structure :
|
||||
1. `module` which is a set of methods
|
||||
2. `method` which have input, output, permissions, and is bound to a function
|
||||
|
||||
So each of your functionalities must have a `method` name and be inside a `module`.
|
||||
|
||||
<u>Example:</u>
|
||||
* module `article` contains methods:
|
||||
* `read` with argument `article_id`
|
||||
* `write` with arguments `title` and `body`
|
||||
* `edit` with arguments `article_id` and `body`
|
||||
* `delete` with argument `article_id`
|
||||
|
||||
If you want to delete the article of id `52`, I must request `article/delete` passing `article_id`=`52`.
|
||||
|
||||
2 - Usage
|
||||
----
|
||||
#### (1) Setup
|
||||
## (1) Setup
|
||||
In order to make the API work, you have to :
|
||||
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))
|
||||
3. Implement the code of the methods according to the configuration
|
||||
|
||||
|
||||
#### (2) Php requirements
|
||||
## (2) Php requirements
|
||||
|
||||
> ##### 1) include the `autoloader` file
|
||||
> ### 1) include the `autoloader` file
|
||||
|
||||
```php
|
||||
<?php
|
||||
require_once '../autoloader.php';
|
||||
<?php require_once '../autoloader.php';
|
||||
```
|
||||
|
||||
> ##### 2) load useful classes
|
||||
> ### 2) load useful classes
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
...
|
||||
|
||||
// for API use
|
||||
use \api\core\Request;
|
||||
use \api\core\Response;
|
||||
|
|
@ -100,65 +105,44 @@ In order to make the API work, you have to :
|
|||
|
||||
|
||||
|
||||
#### (3) From php internally
|
||||
## (3) From php internally
|
||||
|
||||
|
||||
> ##### 1) create a request
|
||||
> ### 1) create a request
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
...
|
||||
|
||||
// creates a request for the module {module} and its method {method} with params
|
||||
$request = new Request('{module}/{method}', [
|
||||
'param1' => 10,
|
||||
'param2' => 'somevalue'
|
||||
]);
|
||||
|
||||
```
|
||||
|
||||
> ##### 2) catch possible errors (optional)
|
||||
> ### 2) catch possible errors (optional)
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
...
|
||||
|
||||
// if error is not Err::Success
|
||||
if( $request->error->get() !== Err::Success )
|
||||
'do something';
|
||||
```
|
||||
|
||||
> ##### 3) execute the request and catch response
|
||||
> ### 3) execute the request and catch response
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
...
|
||||
|
||||
$response = $request->dispatch();
|
||||
```
|
||||
|
||||
> ##### 4) catch response errors (optional)
|
||||
> ### 4) catch response errors (optional)
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
...
|
||||
|
||||
// if error is not Err::Success
|
||||
if( $response->error->get() !== Err::Success )
|
||||
'do something';
|
||||
```
|
||||
|
||||
> ##### 5) catch response output
|
||||
> ### 5) catch response output
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
...
|
||||
|
||||
// fetch all outputs
|
||||
$output = $response->getAll();
|
||||
|
||||
|
|
@ -167,29 +151,22 @@ In order to make the API work, you have to :
|
|||
```
|
||||
|
||||
|
||||
#### (4) From HTTP requests
|
||||
## (4) From HTTP requests
|
||||
In order to setup an automatic bound from HTTP requests to API directly, you must use a **router**.
|
||||
|
||||
|
||||
> ##### 1) Format url so it must begin with `/{module}/{method}`
|
||||
> ### 1) Format url so it must begin with `/{module}/{method}`
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
...
|
||||
|
||||
// let's suppose the url is `/api/{module}/{method}`
|
||||
$url = '/api/somemodule/somemethod/1/2/';
|
||||
$url = substr($url, strlen('/api'));
|
||||
// $url = /somemodule/somemethod/1/2/
|
||||
```
|
||||
|
||||
> ##### 2) give the url to the HTTP manager
|
||||
> ### 2) give the url to the HTTP manager
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
...
|
||||
|
||||
// create request from HTTP data
|
||||
$request = Request::remote($url);
|
||||
|
||||
|
|
@ -204,24 +181,39 @@ In order to setup an automatic bound from HTTP requests to API directly, you mus
|
|||
|
||||
|
||||
Then can handle various kinds of URL :
|
||||
|
||||
- request and parameters can be in URL (separated by `/`)
|
||||
- request and parameters can be in `multipart/form-data` or `x-www-form-urlencoded`
|
||||
- request and parameters of both URL, post data, and form-data are caught
|
||||
|
||||
### The following examples can work :
|
||||
> 1. `http://www.host.com/{module}/{method}/`
|
||||
|
||||
- parameters can be in URL (separated by `/`)
|
||||
- parameters can be in `multipart/form-data` or `x-www-form-urlencoded`
|
||||
- parameters of both URL and content are caught
|
||||
|
||||
> 2. `http://www.host.com/api/{module}/{method}/`
|
||||
|
||||
- parameters can be in URL (separated by `/`)
|
||||
- parameters can be in `multipart/form-data` or `x-www-form-urlencoded`
|
||||
- parameters of both URL and content are caught
|
||||
|
||||
> 3. `http://www.host.com/`
|
||||
|
||||
|
||||
> 4. `https://www.host.com/api/`
|
||||
|
||||
**Case 2**: You want an URL like `http://www.host.com/api/` and pass all data through POST or form-data.
|
||||
```json
|
||||
"post-data": {
|
||||
"param1": "{value1}",
|
||||
"param2": "{value2}"
|
||||
}
|
||||
```
|
||||
> 2. `http://www.host.com/{module}/{method}/{param1}/{param2}`
|
||||
```json
|
||||
"post-data": {}
|
||||
```
|
||||
> 3. `http://www.host.com/apiOrParentUrl/`
|
||||
```json
|
||||
"post-data": {
|
||||
"module": "{module}",
|
||||
"method": "{method}",
|
||||
"param1": "{value1}",
|
||||
"param2": "{value2}"
|
||||
}
|
||||
```
|
||||
> 4. `http://www.host.com/apiOrParentUrl/{value1}/{value2}`
|
||||
```json
|
||||
"post-data": {
|
||||
"module": "{module}",
|
||||
"method": "{method}",
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
3 - configuration
|
||||
|
|
@ -264,19 +256,52 @@ Then can handle various kinds of URL :
|
|||
|`{desc_output}`|Your output's description|"Article content"|
|
||||
|
||||
|
||||
4 - implementation
|
||||
----
|
||||
|
||||
## (1) Permissions : AuthSystem
|
||||
|
||||
In order to implement your _Authentification System_ you have to implement the **interface** `AuthSystem` located in `/build/api/core/AuthSystem`.
|
||||
|
||||
You must register your custom authentification system before each api call with :
|
||||
```php
|
||||
// let's suppose your auth system class is "AuthSystemDefault"
|
||||
\api\core\Request::setAuthSystem(new AuthSystemDefault);
|
||||
```
|
||||
|
||||
## (2) Modules & methods
|
||||
|
||||
### Module implementation
|
||||
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**.
|
||||
|
||||
### Method implementation
|
||||
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.
|
||||
|
||||
_Notes_:
|
||||
* Optional parameters if not given are set to `null`
|
||||
* parameters of type `FILE` are given by reference but the use is the same as normal parameters
|
||||
|
||||
### Ouput required
|
||||
|
||||
You must return an associative array containing at least the field `error` containing an instance of `/api/core/Error`, then you can add useful return.
|
||||
|
||||
If you don't return the 'error' field, by default it is set to `new Error(Err::Success)`.
|
||||
|
||||
5 - class documentation
|
||||
----
|
||||
|
||||
#### (4) Checker
|
||||
## (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
|
||||
### Default types
|
||||
|Type|Example|Description|
|
||||
|---|---|---|
|
||||
|`mixed`|`[9,"a"]`, `"a"`|Any content (can be simple or complex)|
|
||||
|
|
@ -294,7 +319,7 @@ To add a new type, just open the file `/build/api/Checker.php` and add an entry
|
|||
|`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
|
||||
### Complex type : chainable array
|
||||
|
||||
|Type|Sub-Type|Description|
|
||||
|---|---|---|
|
||||
|
|
|
|||
Loading…
Reference in New Issue