From 9e569f861ce6e1dc222a54afd16859e5309561af Mon Sep 17 00:00:00 2001 From: xdrm-brackets Date: Sun, 11 Dec 2016 15:22:39 +0100 Subject: [PATCH] api:2.2 notice in progress 1 --- README.md | 55 +------- notice/api/2.2.md | 137 +++++++++++++++++++- src/packages/api/2.2/module/RESTexample.php | 6 +- 3 files changed, 140 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index c2d4572..8846c1d 100644 --- a/README.md +++ b/README.md @@ -49,59 +49,10 @@ xdrm-framework is based on `all in config` so you will have this structure : #### 3.1 API - self-managed API -###### How to use -In order to use the API, you must begin by writting your _"methods"_ in the configuration file located at `/config/modules.json`. -In order to be understood, lets call `module` a group of methods, and `method` a function which outputs data from input parameters. +> 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) -**Configuration format** -```json -{ - - "{module_name}": { - - "{http_method}::{method_name}": { - "description": "{method_description}", - "permissions": ["{method_perm}"], - "options": { "download": "{is_downloadable}" }, - "parameters": { - "{name_param}": { "description": "{desc_param}", "type": "{type_param}", "optional": "{is_optional}" } - }, - "output": { - "{name_output}": { "description": "{desc_output}", "type": "{type_output}" } - } - } - - } -} - -``` - -|variable|description|exemple| -|-------|-------|------| -|`{module_name}`|alphanumeric module name|"publications"| -|`{http_method}`|uppercase HTTP method|"POST"| -|`{method_name}`|alphanumeric method name|"article"| -|`{method_description}`|textual description|"Returns a specific article"| -|`{method_perm}`|permission array|`["poster", "admin", "user"]`| -|`{is_downloadable}`|If you want this method to return a file|`true`, `false`| -|`{name_param}`|Your param's name|"id_article"| -|`{desc_param}`|Your param's description|"Wanted article's id"| -|`{type_param}`|Your param's type (cf. Checker)|"Wanted article's type"| -|`{is_optional}`|Whether to make your param _required_|`true`, `false`| -|`{name_output}`|Your output's name|"article"| -|`{desc_output}`|Your output's description|"Article content"| - -**Implementation** -TODO - - -###### Classes (advanced) -The API is managed through 5 classes : -1. Request - is the core of the module -2. Response - renders and manages the responses -3. Authentification - manages the authentification part (it has to be over written for each case) -4. Checker - manages auto checked parameters' types -5. ModuleFactory - to instanciate each module, transparent to the user #### [3.2] error - error system #### [3.3] database - database wrapper and repository manager diff --git a/notice/api/2.2.md b/notice/api/2.2.md index 63ebdd7..5a796a1 100644 --- a/notice/api/2.2.md +++ b/notice/api/2.2.md @@ -2,15 +2,142 @@ > version: 2.2 > requires: http:1.0, error:2.0 -#### I. basic knowledge +## I. basic knowledge -#### II. features +#### 1. Types of API you can create +The `api` can be used as a REST API because it manages HTTP methods but if you don't mind, you can use it as an only-POST api for instance. +#### 2. Basic structure +The api works on a 2-level delegation structure : + +|level|name|description +|--|--|--| +|1|module|Representing entity or other kind of wrapper for a set of _methods_| +|2|method|Part of a _module_, have inputs, outputs, permissions, and is bound to a function| -#### III. components and files +## II. features -#### IV. configuration +* HTTP methods +* `optional` & `required` parameters +* parameters types auto-checker +* multiple permissions +* implementable Authentification (permission management) +* `2-level` api (**module** containing **methods**) +* not-POST (_PUT_, _PATCH_, etc) methods `multipart/form-data` parsing +* before and after scripts -#### V. implementation +## III. components and files + +## IV. How to use ? + +#### 1. Set up +To make your api work, you have to: +1. edit the configuration (mode details [here](#IV. configuration)) +2. create the modules classes and implement their methods according to your configuration (mode details [here](#V. implementation)) + +#### 2. Internal use in php +You can use your api from php directly without using HTTP request. + +First, you must require the `autoloader` file and load the API. + +```php + 'someusername']; // and the parameters + + // 1. Create the request + $request = new Request("$module/$method", $params); + + // 2. Execute request and catch response + $response = $request->dispatch(); + + // 3. Get response error code + $error_code = $response->error->get(); + + // 4. Get response output + $output = $response->getAll(); + +``` + + +#### 3. HTTP Request use in php +In order to setup an automatic bound from HTTP requests to API directly, you must use a router. Then you have some possibilities : + +**Case 1**: You want an URL like `http://www.host.com/{module}/{method}/` and pass parameters through POST or form-data. In order to set it up, you must catch the url starting at `/{module}/{method}` so you have to truncate the beginning (for instance if you have /api/{module}/..) + +**Case 2**: You want an URL like `http://www.host.com/api/` and pass all data through POST or form-data. + +## V. configuration + + +###### How to use +In order to use the API, you must begin by writting your _"methods"_ in the configuration file located at `/config/modules.json`. +In order to be understood, lets call `module` a set of methods, and `method` a function which outputs data from input parameters. + +**Configuration format** +```json +{ + + "{module_name}": { + + "{http_method}::{method_name}": { + "description": "{method_description}", + "permissions": ["{method_perm}"], + "options": { "download": "{is_downloadable}" }, + "parameters": { + "{name_param}": { "description": "{desc_param}", "type": "{type_param}", "optional": "{is_optional}" } + }, + "output": { + "{name_output}": { "description": "{desc_output}", "type": "{type_output}" } + } + } + + } +} + +``` + +|variable|description|exemple| +|-------|-------|------| +|`{module_name}`|alphanumeric module name|"publications"| +|`{http_method}`|uppercase HTTP method|"POST"| +|`{method_name}`|alphanumeric method name|"article"| +|`{method_description}`|textual description|"Returns a specific article"| +|`{method_perm}`|permission array|`["poster", "admin", "user"]`| +|`{is_downloadable}`|If you want this method to return a file|`true`, `false`| +|`{name_param}`|Your param's name|"id_article"| +|`{desc_param}`|Your param's description|"Wanted article's id"| +|`{type_param}`|Your param's type (cf. Checker)|"Wanted article's type"| +|`{is_optional}`|Whether to make your param _required_|`true`, `false`| +|`{name_output}`|Your output's name|"article"| +|`{desc_output}`|Your output's description|"Article content"| + + +###### Classes (advanced) +The API is managed through 5 classes : +1. Request - is the core of the module +2. Response - renders and manages the responses +3. Authentification - manages the authentification part (it has to be over written for each case) +4. Checker - manages auto checked parameters' types +5. ModuleFactory - to instanciate each module, transparent to the user + +## VI. implementation + +For the implementation let's assume that your module is `xmodulex` and your method diff --git a/src/packages/api/2.2/module/RESTexample.php b/src/packages/api/2.2/module/RESTexample.php index d2d9114..f3d929a 100644 --- a/src/packages/api/2.2/module/RESTexample.php +++ b/src/packages/api/2.2/module/RESTexample.php @@ -50,7 +50,11 @@ class RESTexample{ if( !$success ) return ['error' => new Error(Err::ModuleError)]; // or other `Err` constant - return ['articles' => "Article number `$URL_0`: sometitle / somecontent"]; + // optional param not given is set to null + if( is_null($URL_0) ) + return ['articles' => [ "Article number `1`: sometitle / somecontent", "Article number `2`: sometitle / somecontent"] ]; + else + return ['articles' => [ "Article number `$URL_0`: sometitle / somecontent"] ]; break; case 'VIEW':