# 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.

## Installation

Download source code and add to your project

```php
<?php
require_once __DIR__ . '/APIlite/src/APIlite.php';
```

or use composer

```bash
composer require tpsoft/apilite
```

and add to your project

```php
<?php
require __DIR__ . '/vendor/autoload.php';

class YourAPI extends \TPsoft\APIlite\APIlite {

	/**
	 * My first method for greetings.
	 *
	 * @param string $name Your name
	 * @param int $age Your age
	 * @return string Greetings
	 */
	public function myFirstMethod(string $name, int $age): string
	{
		return 'Hi, I`m '.$name.' and I`m '.$age.' years old.';
	}

}
```

## 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-06-12 06:24:33 */

class APIcalculator {
	endpont = "http://";

	/* ----------------------------------------------------
		* 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});
	}

};

export default new BackendAPI();
```

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

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