314 lines
8.2 KiB
Markdown
314 lines
8.2 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",
|
|
"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`
|