# 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",
  "javascript_version": "http://localhost/APIlite/test/APIcalculator.php?format=javascript",
  "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" />

The HTML documentation page also includes a built-in interactive tester. Each endpoint can be expanded with `Try it`, filled directly in the browser, and executed against the current API endpoint. If needed, you can set a shared Bearer token at the top of the page. The token is stored in `localStorage` and is sent as `Authorization: Bearer ...` for test requests made from that page.

You can also download generated frontend clients:

* JavaScript: `?format=javascript`
* TypeScript (typed for Vue/TS projects): `?format=typescript`

JavaScript usage example:

```js
import backend from './backend.js';

backend.add(1, 2).then((response) => {
	console.log(response.data);
});
```

TypeScript usage example (Vue + TS):

```ts
import backend from './backend';

backend.add(1, 2).then((response) => {
	console.log(response.data); // typed value based on PHP return type
});
```

If a method return type is a PHP class with public properties, JSON help now also includes `return_structure`, and the generated TypeScript client maps that class to an object shape based on those public properties.

These outputs can also be generated in command line:

* HTML: `$> php APIcalculator.php --html`
* JavaScript: `$> php APIcalculator.php --javascript > backend.js` (`--js` alias is available)
* TypeScript: `$> php APIcalculator.php --typescript > backend.ts`

## HTML help tester notes

The built-in HTML tester currently follows the default APIlite request model:

* request method is `POST`
* endpoint action is sent as query parameter `action`
* request fields are sent as top-level form fields
* object and array field values are serialized as JSON strings

Because the current metadata does not explicitly distinguish path params, query params and request body schemas, the HTML tester renders the parts that are reliably available today and keeps the rest minimal.