From a23fbce67d853479925303f7791aa2b441670d68 Mon Sep 17 00:00:00 2001 From: xdrm-brackets Date: Tue, 12 Dec 2017 23:51:47 +0100 Subject: [PATCH] upd: notice.api:3.0 (updated for now, TODO: update links) --- notice/api/3.0.md | 165 +++++++++++++++++----------------------------- 1 file changed, 61 insertions(+), 104 deletions(-) diff --git a/notice/api/3.0.md b/notice/api/3.0.md index b9515ec..439ae9d 100644 --- a/notice/api/3.0.md +++ b/notice/api/3.0.md @@ -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 - 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 - 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 -`|`a`|Array containing only entries matching the type `a`| > **Note:** It is possible to chain `array` type as many as needed. -**Ex.:** `array>` - Will match array only containing arrays that only contains `id` entries. +**Ex.:** `array>` - Will only match an array containing arrays that only contains `id` entries. -## **5** Advanced +## **4** Advanced ### Before and After scripts