diff --git a/notice/api/2.2.md b/notice/api/2.2.md index 0a13b24..739f110 100644 --- a/notice/api/2.2.md +++ b/notice/api/2.2.md @@ -9,38 +9,42 @@ requires: Links ==== -[[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) php requirements](#2-php-requirements) - - [(3) from php internally](#3-from-php-internally) - - [(4) from HTTP requests](#4-from-http-requests) -- [3 - Configuration](#3---configuration) - - [(1) Basic usage](#1-basic-usage) - - [(2) Advanced usage](#2-advanced-usage) -- [4 - Implementation](#4---implementation) - - [(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) - - [(1) Request](#1-request) - - [(2) Response](#2-response) - - [(3) AuthSystem](#4-authsystem) - - [(4) Checker](#4-checker) - - [(4) ModuleFactory](#4-modulefactory) +[**I.** Overview](#I.-overview) -[[2]. Advanced guide]() +- [**1** Introduction & features](#1-introduction--features) +- [**2** Basic knowledge](#2-basic-knowledge) -User guide -==== +[**II.** Usage](#2---usage) -1 - Overview ----- +- [**1** Setup](#1-setup) +- [**2** Php requirements](#2-php-requirements) +- [**3** From php internally](#3-from-php-internally) +- [**4** From HTTP requests](#4-from-http-requests) -## (1) Introduction & features +[**III.** Configuration](#3---configuration) + +- [**1** Basic usage](#1-basic-usage) +- [**2** Advanced usage](#2-advanced-usage) + +[**IV.** Implementation](#4---implementation) + +- [**1** Permissions : AuthSystem](#1-permissions--authsystem) +- [**2** Modules & methods](#2-modules--methods) +- [**3** Automatic type check](#3-automatic-type-check) + +[**V.** Class documentation](#5---class-documentation) + +- [**1** Request](#1-request) +- [**2** Response](#2-response) +- [**3** AuthSystem](#4-authsystem) +- [**4** Checker](#4-checker) +- [**5** ModuleFactory](#4-modulefactory) + + + +> # **I.** Overview + +> ## **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 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. @@ -57,7 +61,7 @@ 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 @@ -74,16 +78,24 @@ So each of your functionalities must have a `method` name and be inside a `modul If you want to delete the article of id `52`, you must request `article/delete` passing `article_id`=`52`. -2 - Usage ----- -## (1) Setup + + + + + + + + +[2] - Usage +==== +> ## **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 @@ -105,7 +117,7 @@ use \error\core\Err; -## (3) From php internally +> ## **3** From php internally > ### 1) create a request @@ -151,7 +163,7 @@ $specific = $response->get('someOutputName'); ``` -## (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**. @@ -216,8 +228,12 @@ Then can handle various kinds of URL : ``` -3 - configuration ----- + + + + +[3] - Configuration +==== ```json { @@ -258,10 +274,16 @@ Then can handle various kinds of URL : _*_ If you want URL (GET) parameters, the {param_name} must be `URL_0`, `URL_1` and so on according to the index wanted in the URL. > `api/module/method/URL_0/URL_1/URL_2/` -4 - implementation ----- -## (1) Permissions : AuthSystem + + + + + +[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`. @@ -271,7 +293,7 @@ You must register your custom authentification system before each api call with \api\core\Request::setAuthSystem(new AuthSystemDefault); ``` -## (2) Modules & methods +> ## **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**. @@ -294,10 +316,13 @@ You must return an associative array containing at least the field `error` conta If you don't return the 'error' field, by default it is set to `new Error(Err::Success)`. -5 - class documentation ----- -## (4) Checker + + +[5] - Class documentation +==== + +> ## **4** Checker `Checker` checks the input values according to the type given in the configuration. @@ -332,7 +357,7 @@ To add a new type, just open the file `/build/api/Checker.php` and add an entry **Ex.:** `array>` - Will match array only containing arrays that only contains `id` entries. -## (5) Advanced +> ## **5** Advanced ### Before and After scripts