264 lines
7.1 KiB
Markdown
264 lines
7.1 KiB
Markdown
# 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" />
|
|
|
|
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
|
|
});
|
|
```
|
|
|
|
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`
|