Fusio

Requirements

Fusio is written in PHP and requires at least version 7. If you want to write your backend code in javascript you also have to install the PHP-V8 extension. In order to run the installation script you have to access the command-line interface of the webserver.

  • PHP >= 7
  • MySQL/Postgres database
  • CLI access

Installation

To install Fusio download the latest version and place the folder into the www directory of the webserver. After this Fusio can be installed in the following steps.

  • Adjust the configuration file

    Open the file configuration.php in the Fusio directory and change the key psx_url to the domain pointing to the public folder. Also insert the database credentials to the psx_connection keys.

  • Execute the installation command

    The installation script inserts the Fusio database schema into the provided database. It can be executed with the following command php bin/fusio install.

  • Create administrator user

    After the installation is complete you have to create a new administrator account. Therefor you can use the following command php bin/fusio adduser. Choose as account type "Administrator".

Now you are able to login to the backend at /fusio.

Build an API endpoint

Fusio provides a demo todo API which is ready for deployment. Take a look at the .fusio.yml file which contains the deployment configuration. The file contains several keys:

  • routes

    Describes for each route the available request methods, whether the endpoint is public or private, the available request/response schema and also the action which should be executed:

    routes:
      "/todo":
        version: 1
        methods:
          GET:
            public: true
            response: Todo-Collection
            action: Todo-List
          POST:
            public: false
            request: Todo
            response: Todo-Message
            action: Todo-Insert
  • schema

    Contains the available request and response schema in the JSON-Schema format:

    schema:
      Todo: !include resources/schema/todo/entity.json
      Todo-Collection: !include resources/schema/todo/collection.json
      Todo-Message: !include resources/schema/todo/message.json
  • action

    Contains the actual actions which are executed if an request arrives and which produce the response:

    action:
      Todo-List:
        class: Fusio\Custom\Action\Todo\Collection
      Todo-Row:
        class: Fusio\Custom\Action\Todo\Row
      Todo-Insert:
        class: Fusio\Custom\Action\Todo\Insert
      Todo-Delete:
        class: Fusio\Custom\Action\Todo\Delete
  • connection

    Provides connections to a remote service i.e. mysql or mongodb. This connection can be used inside an action:

    connection:
      Default-Connection:
        class: Fusio\Adapter\Sql\Connection\SqlAdvanced
        config:
          url: "sqlite:///${dir.cache}/todo-app.db"
  • migration

    Through migrations it is possible to execute i.e. sql queries on a connection. This allows you to change your database schema on deployment.

    migration:
      Acme-Mysql:
        - resources/sql/v1_schema.sql

Through the command php bin/fusio deploy you can deploy the API. It is now possible to visit the API endpoint at: /todo.

Access a non-public API endpoint

The POST method of the todo API is not public, because of this you need an access token in order to post a request.

  • Create a scope

    At first we must create a scope for the /todo API endpoint. Therefor login to the backend an go to the scope panel. Click on the plus button and create a new scope todo which has the /todo route assigned.

  • Assign the scope to your user

    In order to use a scope, the scope must be assigned to your user account. Therefor go to the user panel click on the edit button and assign the todo scope to your user.

  • Request a JWT

    Now you can obtain a JWT through a simple HTTP request to the consumer/login endpoint.

    POST /consumer/login HTTP/1.1
    Host: 127.0.0.1
    Content-Type: application/json
    
    {
      "username": "[username]",
      "password": "[password]"
    }

    Which returns a token i.e.:

    {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI5N2JkNDUzYjdlMDZlOWFlMDQxNi00YmY2MWFiYjg4MDJjZmRmOWZmN2UyNDg4OTNmNzYyYmU5Njc5MGUzYTk4NDQ3MDEtYjNkYTk1MDYyNCIsImlhdCI6MTQ5MTE2NzIzNiwiZXhwIjoxNDkxMTcwODM2LCJuYW1lIjoidGVzdCJ9.T49Af5wnPIFYbPer3rOn-KV5PcN0FLcBVykUMCIAuwI"
    }
  • Request the non-public API endpoint

    Now we can use the JWT as Bearer token in the Authorization header.

    POST /todo HTTP/1.1
    Host: 127.0.0.1
    Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI5N2JkNDUzYjdlMDZlOWFlMDQxNi00YmY2MWFiYjg4MDJjZmRmOWZmN2UyNDg4OTNmNzYyYmU5Njc5MGUzYTk4NDQ3MDEtYjNkYTk1MDYyNCIsImlhdCI6MTQ5MTE2NzIzNiwiZXhwIjoxNDkxMTcwODM2LCJuYW1lIjoidGVzdCJ9.T49Af5wnPIFYbPer3rOn-KV5PcN0FLcBVykUMCIAuwI
    Content-Type: application/json
    
    {
      "title": "lorem ipsum"
    }

Summarize

This was a quick introduction how to build and consume an API with Fusio. Please take a look at the documentation section for more resources.