Introduction
With Fusio it is possible to develop API endpoints serverless through a simple backend. Therefor you can use many predefined actions i.e. to create an API based on a SQL database. The following video gives a small introduction to Fusio.
Development
For more advanced endpoints it is also possible to use the deploy system where you only have to describe the capabilities of each API endpoint in a simple yaml file. All other aspects of the API lifecycle are managed by Fusio. So you can concentrate on building the actual business logic of your API.
# Routes
routes:
"/todo": !include resources/routes/todo/collection.yaml
"/todo/:todo_id": !include resources/routes/todo/entity.yaml
# Schemas
schema:
Todo: !include resources/schema/todo/entity.json
Todo-Collection: !include resources/schema/todo/collection.json
Message: !include resources/schema/message.json
# Connections
connection:
Default-Connection:
class: Fusio\Adapter\Sql\Connection\SqlAdvanced
config:
url: "sqlite:///${dir.cache}/todo-app.db"
version: 1
methods:
GET:
public: true
responses:
200: Todo-Collection
500: Message
action: "${dir.src}/Todo/collection.php"
POST:
public: false
request: Todo
responses:
201: Message
500: Message
action: "${dir.src}/Todo/insert.php"
<?php
/**
* @var \Fusio\Engine\ConnectorInterface $connector
* @var \Fusio\Engine\RequestInterface $request
* @var \Fusio\Engine\Response\FactoryInterface $response
* @var \Fusio\Engine\ProcessorInterface $processor
* @var \Psr\Log\LoggerInterface $logger
* @var \Psr\SimpleCache\CacheInterface $cache
*/
/** @var \Doctrine\DBAL\Connection $connection */
$connection = $connector->getConnection('Default-Connection');
$count = $connection->fetchColumn('SELECT COUNT(*) FROM app_todo');
$entries = $connection->fetchAll('SELECT * FROM app_todo WHERE status = 1 ORDER BY insertDate DESC LIMIT 16');
return $response->build(200, [], [
'totalResults' => $count,
'entry' => $entries,
]);
{
"type": "object",
"title": "todo",
"properties": {
"id": {
"type": "integer"
},
"status": {
"type": "integer"
},
"title": {
"type": "string",
"minLength": 3,
"maxLength": 32
},
"insertDate": {
"type": "string",
"format": "date-time"
}
},
"required": ["title"]
}
Features
Once the API is deployed Fusio provides the following features out of the box:
Developer portal
Fusio provides a developer portal app where developer can register to use your API.
Monetization
Fusio provides a simple payment system to charge for specific routes.
OAuth2 authorization
App developer can obtain an access token to access non-public API endpoints.
Rate limiting
Fusio provides a way to rate limit requests based on the user or app.
Schema generation
Fusio provides an endpoint to automatically generate OAI and RAML specifications.
Subscription support
Fusio contains a subscription layer which helps to build pub/sub for your API.
Scope handling
Each user and app can be limited to scopes to request only specific parts of the API.
A route is the rule which redirects the incoming request to an action. If a request arrives the first route which matches is used. In order to be able to evolve an API it is possible to add multiple versions for the same route. For each version it is possible to specify the allowed request methods. Each method describes the request and response schema and the action which is executed upon request. If a request method is public it is possible to request the API endpoint without an access token.
version: 1
methods:
GET:
public: true
responses:
200: Todo-Collection
action: "${dir.src}/Todo/collection.php"
POST:
public: false
request: Todo
responses:
200: Todo-Message
action: "${dir.src}/Todo/insert.php"The request and responses key reference a schema
name. It is also possible to use the Passthru schema which simply
redirects all data. The action key reference an action.
The schema defines the format of the request and response data. It uses the
popular JsonSchema format. Inside a
schema it is possible to refer to other schema definitions by using the
$ref key and the file protocol i.e. file:///[file].
{
"id": "http://acme.com/schema",
"type": "object",
"title": "schema",
"properties": {
"name": {
"type": "string"
},
"author": {
"$ref": "file:///author.json"
},
"date": {
"type": "string",
"format": "date-time"
}
}
}A connection provides a class which helps to connect to another service.
Each connection returns an object to simplify the communication with the
service. I.e. the sql connection returns a Doctrine\DBAL\Connection
instance.
Acme-Mysql:
class: Fusio\Adapter\Sql\Connection\Sql
config:
type: pdo_mysql
host: localhost
username: root
password: test
database: fusioThere are already many connection types available to popular services like i.e. SQL, MongoDB, HTTP, AMQP, Elasticsearch. Also through the adapter system it is easy possible to create new connection types.
action: "${dir.src}/Todo/collection.php"If the action points to a file with a php file extension
Fusio simply includes this file. In the following an example
implementation:
<?php
/**
* @var \Fusio\Engine\ConnectorInterface $connector
* @var \Fusio\Engine\ContextInterface $context
* @var \Fusio\Engine\RequestInterface $request
* @var \Fusio\Engine\Response\FactoryInterface $response
* @var \Fusio\Engine\ProcessorInterface $processor
* @var \Psr\Log\LoggerInterface $logger
* @var \Psr\SimpleCache\CacheInterface $cache
*/
// @TODO handle request and return response
$response->build(200, [], [
'message' => 'Hello World!',
]);action: "${dir.src}/Todo/collection.js"If the action points to a file with a js file extension Fusio uses
the internal v8 engine to execute the js code. This is suitable for
javascript developers who like to write the code in javascript.
Note the v8 implementation requires the php v8
extension. In the following an example implementation:
response.setStatusCode(200);
response.setBody({
message: "Hello World!"
});
action: "http://foo.bar"If the action contains an http or https url
the request gets forwarded to the defined endpoint. Fusio automatically
adds some additional headers to the request which may be used by the
endpoint i.e.:
X-Fusio-Route-Id: 72
X-Fusio-User-Anonymous: 1
X-Fusio-User-Id: 4
X-Fusio-App-Id: 3
X-Fusio-App-Key: 1ba7b2e5-fa1a-4153-8668-8a855902edda
X-Fusio-Remote-Ip: 127.0.0.1
action: "${dir.src}/static.json"If the action points to a simple file Fusio will simply forward the content to the client. This is helpful if you want to build fast an sample API with dummy responses.
action: "App\\Todo\\CollectionAction"If the action string is a PHP class Fusio tries to autoload this class
through composer. The class must implement the Fusio\Engine\ActionInterface.
This is the most advanced solution since it is also possible to access
services from the DI container. In the following an example implementation:
<?php
namespace App\Todo;
use Fusio\Engine\ActionAbstract;
use Fusio\Engine\ContextInterface;
use Fusio\Engine\ParametersInterface;
use Fusio\Engine\RequestInterface;
class CollectionAction extends ActionAbstract
{
public function handle(RequestInterface $request, ParametersInterface $configuration, ContextInterface $context)
{
// @TODO handle request and return response
return $this->response->build(200, [], [
'message' => 'Hello World!',
]);
}
}
Inside an action you can access every connection which is defined in the
connections.yaml definition. Each connection returns an object
which helps you to work with the service. I.e. the sql connection returns a
Doctrine\DBAL\Connection instance.
There are already many connection types available to popular services like i.e. SQL, MongoDB, HTTP, AMQP, Elasticsearch. Also through the adapter system it is easy possible to create new connection types.