xdrm-framework/notice/api/2.2.md

module: api version: 2.2 requires: http:1.0, error:2.0

I. basic knowledge

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

II. features

• 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

III. components and files

The API core is build over 5 classes:

1. Request - is the core of the package

2. Response - renders and manages the responses
3. Authentification - manages the authentification part (it has to be over written for each project)
4. Checker - manages auto checked types for input parameters
5. ModuleFactory - used to instanciate each module, transparent to the user

The API file structure is composed with :

1. the configuration file is located at /config/modules.php.

2. the core folder located at /build/api/core/
3. the module's implementation folder located at /build/api/module/

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 require_once '../autoloader.php'

	use \api\core\Request;
	use \api\core\Request;

Then, you must pass the module, the method and the parameters.

<?php require_once '../autoloader.php'

	use \api\core\Request;
	use \api\core\Request;

	$module = 'user';                        // the module 'user'
	$method = 'getUsername';                 // and its method 'getUsername'
	$params = ['id_user' => '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

{

	"{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"

VI. implementation

For the implementation let's assume that /config/modules.json looks like this

{
	"user": {
		"POST::sign_in": {
			""
		}
	}

}