xdrm-framework/notice/api/2.0.md

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

Links

[1] User guide

• 1 - Overview
  • (1) introduction & features
  • (2) basic knowledge
• 2 - Usage
  • (1) setup
  • (2) from php internally
  • (3) from HTTP requests
• 3 - Configuration
  • (1) Basic usage
  • (2) Advanced usage
• 4 - Implementation
  • (1) Permissions / AuthSystem
  • (2) Modules & methods
  • (3) Automatic type check
• 5 - Class documentation
  • (1) Request
  • (2) Response
  • (3) AuthSystem
  • (4) Checker
  • (4) ModuleFactory

[2]. Advanced guide

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.

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.

Things you have to do :

• implement your processes (obviously)
• implement your authentication system (cf. AuthSystem)
• edit the configuration file (cf. configuration)

Things you don't have to do :

• input type check (cf. Checker)
• API multiple permission management
• optional or required inputs
• before and after scripts

(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

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)
2. Implement the Authentication System to manage permissions (cf. AuthSystem)

(2) From php internally

1) include the autoloader file

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

2) load useful classes

<?php

	...

	// for API use
	use \api\core\Request;
	use \api\core\Response;

	// for error handling
	use \error\core\Err;

3) create a request

<?php

  ...

  // creates a request for the module {module} and its method {method} with params
  $request = new Request('{module}/{method}', [
  	'param1' => 10,
  	'param2' => 'somevalue'
  ]);

4) catch possible errors (optional)

<?php

  ...

  // if error is not Err::Success
	if( $request->error->get() !== Err::Success )
		'do something';

5) execute the request and catch response

<?php

  ...

	$response = $request->dispatch();

6) catch response errors (optional)

<?php

  ...

  // if error is not Err::Success
	if( $response->error->get() !== Err::Success )
		'do something';

7) catch response output

<?php

  ...

  // fetch all outputs
	$output = $response->getAll();

  // fetch specific output
  $specific = $response->get('someOutputName');

(3) From HTTP requests

5 - class documentation

(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

Type	Example	Description
mixed	[9,"a"], "a"	Any content (can be simple or complex)
id	10, "23"	Positive integer number between 0 and 2147483647
numeric	-10.2, "23"	Any number, null and the string "null"
text	"Hello!"	String that can be of any length (even empty)
hash	"4612473aa81f93a878674f9ebffa8d63a1b51ea28dcdcdb1e89eb512aae9b77e"	String with a length of 40 or 64, containing only hexadecimal characters
alphanumeric	"abc029.-sd9"	String containing only alphanumeric, ___, -, and . characters
letters	"abc -sd"	String containing only letters, -, and space characters
mail	"a.b@c.def"	Valid email address
number	0102030405	Phone number, following formats allowed : 06, +336, +33 6
array	[1, 3]	Non-empty array
object	works only within php	Non-empty object
boolean	true, false	Boolean
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

Type	Sub-Type	Description
array<a>	a	Array containing only entries matching the type a

Note: It is possible to chain array type as many as needed.
Ex.: array<array<id>> - Will match array only containing arrays that only contains id entries.

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 internally 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": {
			""
		}
	}

}