Web services REST API Module

Introduction

REST API is considered as “a representational state transfer technology”, which is an architectural style of communicating within the web service development systems. This module in Tactic helps in marinating a communication between the software and the web services. The users need to enable this module with enabling the web services and their usage provided by Tactic server. The users will then be able to make REST calls of diverse web services that is provided by Tactic.

Installation

For proceeding with the installation of REST API, the users need to activate the REST API module from the setup page. After activating the Web service REST API module the users will be able to send their own request related to REST to a relative URL. The users will be able to find the list of APIs from the explorer. Any API can be selected based on the user preferences.

Apache setup

There is nothing complex about the Apache setup, if Tactic works with Apache REST API will also be working without any issues. The APIs will be served by the same virtual web server as the software.

Nginx setup

The setup of Nginx is almost similar to Apache. It will also be served with the same virtual web server as the software. However, there can be several issues that can be faced by Nginx default set up. The user can easily edit their Nginx configuration file for enhancing their user experience and for mitigating the associated issues effectively.

List of services

There are several and diverse services that are provided by Tactic. The full list of Tactic provided web services can be found in the following link: http://localhost/tactic/htdocs/societe/list.php The demo version of explorer can be tried at: http://localhost/tactic/htdocs/societe/list.php For exploring the web services the users need to paste the token of user at the top right corner. Then the users need to press the explore button for exploring through the API. However, for enjoying this facility the users first need to log-in to the API services. Upon clicking the option of explore, the users need to go through all of the actions that are available. However, the available actions majorly depend on the activated modules. If the modules are not activated there will be no actions available on the API for exploring as well. The users need to use this API page very carefully as any modification in the data in the API page, directly impact the database of the software. The users will be able to test it directly from the API tool. The users will be also be able to get the results of the test as well as an example of calling the API command line using curl.

Usage of REST API

The usage of the API system can be utilised with the assistance of four parameter. The users can use these parameter as per their needs.

• “$method : string, "GET", "POST", "PUT", "DELETE"”
• “$apikey : string, "your <token> generated earlier"”
• “$url : string, url to call. Ex : http://<my_server>/api/index.php/invoices”
• “$data : string, datas in json format. This parameter is not mandatory.”

For working with the REST explorer the users at first need to verify the accepted parameters. The users need try to understand the responses provided by the explorer. If the syntax is right the explorer will provide the user with a source code.

Sqlfilters

Squlfilters are used for filtering the databases that exist in the explorer but are not viewed.

Date

Filters can be used as per the dating system as well. The accepted date format is the ISO format. YY-MM-DD format is not supported, which should be known by the users.

Examples

There can be different examples in different use cases. However, in each example there is:

$apiKey = "<my token>";
$apiUrl = "http://<my_server>/api/index.php/"; 
// Retrieve products list
$listProduits = [];
$produitParam = ["limit" => 1500, "sortfield" => "rowid"]; 
$listProduitsResult = CallAPI("GET", $apiKey, $apiUrl."products", $produitParam);
$listProduitsResult =  json_decode($listProduitsResult, true);
if (isset($listProduitsResult["error"]) &&  $listProduitsResult["error"]["code"] >= "300") {
} else {
foreach ($listProduitsResult as $produit) {
$listProduits[intval($produit["id"])] =  html_entity_decode($produit["ref"], ENT_QUOTES);
 }
   }

In this example:

• The first 1500 products have been retrieved based on their IDs in the base
• It is important to perform a html_entity_decode as every single quote is encoded
• The method of replacing the products with dictionnarycountries can be used for retrieving the list of nations along with their IDs

// Create a product
	 $ref = "my_product_ref_X9418H";
	 $newProduct = [
		"ref"	=> $ref,
		"label"	=> $ref
	];
	 $newProductResult = CallAPI("POST", $apiKey,    $apiUrl."products", json_encode($newProduct));
	 $newProductResult = json_decode($newProductResult,  true);

The users need to check if the product already exists or not before creating a product.

// my ref
	$ref = "my_product_ref_ X9418H";
// does it exist in my array
	$produitKey = array_search($ref, $listProduits);
	if ($produitKey) {
// yes
		$fk_product = $produitKey;
	} else {
// no
// Create the product
		$newProduct = [
			"ref"	=> $ref,
			"label"	=> $ref
		];
		$newProductResult = CallAPI("POST", $apiKey, $apiUrl."products", json_encode($newProduct));
		$newProductResult = json_decode($newProductResult, true);
		if (isset($newProductResult["error"]) && $newProductResult["error"]["code"] >= "300") {
// there's been an error
echo 

"

ERROR", var_dump($newProductResult), "

";

 			exit;
  		} else {
  // everything good
  			$fk_product = $newProductResult;
  			$listProduits[$fk_product] = $ref;
 		}
 	}

In this example:

• The users need to check the existence of the products references in the previously created array
• Upon finding about the existence of product reference, the key of the product need to be used in the array as an ID
• If the product ref does not exist, the product need to be created at first then the array need to be added

/ create an order with 2 products

// The array where there will be all the products lines of my order.

$newCommandeLine = [];

// product 1
 	$ref1 = "my_product_ref_X9418H";
 	$prix1 = 10;
 	$qtt1  = 100;
 	$tva1 = 20;
 	$fk_product1
// product 2
	$ref2 = "my_product_ref_N2903B";
	$prix2 = 13;
	$qtt2  = 37;
	$tva2 = 20;

	$newCommandeLine[] = [
		"desc"		=> $ref1,
   	"subprice"	=> $prix1,
		"qty"		=> $qtt1,
		"tva_tx"	=> floatval($tva1),
		"fk_product"=> $fk_product1
	];

$newCommandeLine[] = [ "desc" => $ref2, "subprice" => $prix2, "qty" => $qtt2, "tva_tx" => floatval($tva2), "fk_product"=> $fk_product2 ];

	if (count($newCommandeLine) > 0) {
		$newCommande = [
			"socid"			=> $clientDoliId,
			"type" 			=> "0",
			"lines"			=> $newCommandeLine,
			"note_private"	=> "order created automatically with API",
		];
		$newCommandeResult = CallAPI("POST", $apiKey, $apiUrl."orders", json_encode($newCommande));
		$newCommandeResult = json_decode($newCommandeResult, true);
	}
 // Validate an order 
	$newCommandeValider = [
		"idwarehouse"	=> "0",
		"notrigger"		=> "0"
	];
	$newCommandeValiderResult = CallAPI("POST", $apiKey, $apiUrl."orders/".$newCommandeResult."/validate",
json_encode($newCommandeValider));
	$newCommandeValiderResult = json_decode($newCommandeValiderResult, true);
// search in the database if a customer exist
	$customer_name = "Acme Inc";
	$clientSearch = json_decode(CallAPI("GET", $apiKey, $apiUrl."thirdparties", array(
	"sortfield" => "t.rowid", 
		"sortorder" => "ASC", 
   	"limit" => "1", 
		"mode" => "1",
	"sqlfilters" => "(t.nom:=:'".$customer_name."')"

)

  ), true);

limit => 1 only 1 customer mode => 1, the user is looking for a customer, not a supplier (they are thirdparties too but with a different status)

// customer doesn't exist. Let's create it and get it's ID
	$newClient = [
		"name" 			=> "customer company name",
		"email"			=> "customer company email",
		"client" 		=> "1",
		"code_client"	=> "-1"
	];
	$newClientResult = CallAPI("POST", $apiKey, $apiUrl."thirdparties", json_encode($newClient));
	$newClientResult = json_decode($newClientResult, true);
	$clientDoliId = $newClientResult;

client => 1, is a customer (not a supplier) code_client => -1 so the customer code will be generated automatically.

Developing the users’ own web service or API

The users can easily add their very own REST service in Tactic. They just need to add a file that is known as api_mymoduleobject.class.php in the directory htdocs/mymodule/class. The module-builder tool can be used in this regard and it can help the users by generating their files. This framework works smartly for the users and detect the API automatically. The methods and parameters are also generated all by themselves but these are detected based on the introspection that is performed into PHP class.