# APIlite

A set of tools to simplify the work of creating backend APIs for your frontend projects. Includes tutorials, patterns and practical examples for creating projects based on REST APIs.

## Basic usage

For example, we create an API for calculator. So we create class `APIcalculator` and store in file `test/APIcalculator.php` where we defined each actions for API as public method.

```php
<?php

/**
 * Class APIcalculator
 *
 * A calculator class that extends the functionality of TPsoft's APIlite.
 * This class provides basic arithmetic operations and a few additional
 * mathematical functions.
 *
 */

require_once __DIR__ . '/../src/APIlite.php';

class APIcalculator extends \TPsoft\APIlite\APIlite
{

	/**
	 * Add two numbers.
	 * Standard plus operation.
	 *
	 * @param float $a The first number.
	 * @param float $b The second number.
	 * @return float The sum of the two numbers.
	 */
	public function add(float $a, float $b): float
	{
		return $a + $b;
	}

	/**
	 * Subtract two numbers.
	 * Standard minus operation.
	 *
	 * @param float $a The first number.
	 * @param float $b The second number.
	 * @return float The difference of the two numbers.
	 */
	public function subtract(float $a, float $b): float
	{
		return $a - $b;
	}

	/**
	 * Multiply two numbers.
	 * Standard multiplication operation.
	 *
	 * @param float $a The first number.
	 * @param float $b The second number.
	 * @return float The product of the two numbers.
	 */
	public function multiply(float $a, float $b): float
	{
		return $a * $b;
	}

	/**
	 * Divide two numbers.
	 * Standard division operation. Throws an exception if dividing by zero.
	 *
	 * @param float $a The first number.
	 * @param float $b The second number.
	 * @return float The quotient of the two numbers. Throws an exception if dividing by zero.
	 * @throws \Exception If dividing by zero.
	 */
	public function divide(float $a, float $b): float
	{
		if ($b == 0) {
			throw new \Exception('Division by zero');
		}
		return $a / $b;
	}
}

new APIcalculator();

```

It is important to extend the `APIcalculator` class with the `\TPsoft\APIlite\APIlite` class, which will provide the entire API servicing according to public methods along with JSON and HTML documentation. The HTML documentation is generated based on the documentation snippet for each method.

## Outputs

When you run this subfile through the webserver, you will see the JSON documentation in the browser

```js
{
  "name": "APIcalculator",
  "html_version": "http://localhost/APIlite/test/APIcalculator.php?format=html",
  "typescript_version": "http://localhost/APIlite/test/APIcalculator.php?format=typescript",
  "actions": [
    {
      "name": "add",
      "doc": "/**\r\n\t * Add two numbers.\r\n\t * Standard plus operation.\r\n\t *\r\n\t * @param float $a The first number.\r\n\t * @param float $b The second number.\r\n\t * @return float The sum of the two numbers.\r\n\t */",
      "description": "Add two numbers.\nStandard plus operation.",
      "params": [
        {
          "name": "a",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The first number."
        },
        {
          "name": "b",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The second number."
        }
      ],
      "return": "float"
    },
    {
      "name": "subtract",
      "doc": "/**\r\n\t * Subtract two numbers.\r\n\t * Standard minus operation.\r\n\t *\r\n\t * @param float $a The first number.\r\n\t * @param float $b The second number.\r\n\t * @return float The difference of the two numbers.\r\n\t */",
      "description": "Subtract two numbers.\nStandard minus operation.",
      "params": [
        {
          "name": "a",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The first number."
        },
        {
          "name": "b",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The second number."
        }
      ],
      "return": "float"
    },
    {
      "name": "multiply",
      "doc": "/**\r\n\t * Multiply two numbers.\r\n\t * Standard multiplication operation.\r\n\t *\r\n\t * @param float $a The first number.\r\n\t * @param float $b The second number.\r\n\t * @return float The product of the two numbers.\r\n\t */",
      "description": "Multiply two numbers.\nStandard multiplication operation.",
      "params": [
        {
          "name": "a",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The first number."
        },
        {
          "name": "b",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The second number."
        }
      ],
      "return": "float"
    },
    {
      "name": "divide",
      "doc": "/**\r\n\t * Divide two numbers.\r\n\t * Standard division operation. Throws an exception if dividing by zero.\r\n\t *\r\n\t * @param float $a The first number.\r\n\t * @param float $b The second number.\r\n\t * @return float The quotient of the two numbers. Throws an exception if dividing by zero.\r\n\t * @throws \\Exception If dividing by zero.\r\n\t */",
      "description": "Divide two numbers.\nStandard division operation. Throws an exception if dividing by zero.",
      "params": [
        {
          "name": "a",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The first number."
        },
        {
          "name": "b",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The second number."
        }
      ],
      "return": "float"
    }
  ]
}
```

and there is also an HTML version available

<img src="test/Example.APIcalculator.png" />

To connect to the API from TypeScript (e.g. Vue application) it is possible to download the backend script

```ts
/**
 * Generated by APIlite
 * https://gitea.tpsoft.org/TPsoft.org/APIlite
 *
 * 2025-05-28 15:44:07 */

export const backend = {
	endpont: window.location.origin + "APIcalculator.php",

	/* ----------------------------------------------------
	 * General API call
	 */
	call(method, data, callback) {
		var xhttp = new XMLHttpRequest();
		xhttp.withCredentials = true;
		xhttp.onreadystatechange = function() {
			if (this.readyState == 4) {
				if (this.status == 200) {
					if (callback != null) callback(JSON.parse(this.responseText));
				} else {
					if (callback != null) callback({'status': 'ERROR', 'message': 'HTTP STATUS ' + this.status});
				}
			}
		}
		var form_data  = new FormData();
		Object.keys(data).forEach(key => {
			let val = data[key];
			if (typeof val == 'object') val = JSON.stringify(val);
			form_data.append(key, val);
		});
		xhttp.open('POST', this.endpont + '?action=' + method);
		xhttp.send(form_data);
	},

	callPromise(method, data) {
		return new Promise((resolve, reject) => {
			this.call(method, data, function(response) {
				if (response.status == 'OK') {
					resolve(response.data);
				} else {
					reject(response.msg);
				}
			});
		})
	},

	/* ----------------------------------------------------
	 * API actions
	 */
	help() {
		return this.callPromise('__HELP__', {});
	},

	add(a, b) {
		return this.callPromise('add', {a: a, b: b});
	},

	subtract(a, b) {
		return this.callPromise('subtract', {a: a, b: b});
	},

	multiply(a, b) {
		return this.callPromise('multiply', {a: a, b: b});
	},

	divide(a, b) {
		return this.callPromise('divide', {a: a, b: b});
	},


};

```

These outputs can also be generated in the command line as follows

* for HTML`$> php APIcalculator.php --html`
* for TypeScript`$> php APIcalculator.php --typescript`