Simple PHP based API Management Platform

This tutorial shows you how to build a clean API using Fusio, which is an open source PHP based API management solution. We are building a simple Todo API where a user can receive and create Todo entries.

To start please head to Github and download the latest release of Fusio. Then you need to move the folder into the document root of your web server. To install Fusio you can use either the web based installer (located at public/install.php) or you can use the CLI installer. There for you need to enter the database credentials to the configuration and run the install command:

php bin/fusio install

To start building an API you have to define at first a route. A route is a path i.e. “/foo/bar” or “/foo/:year” which redirects an incoming request to the fitting action. Every route has a corresponding YAML config file which describes the route:

version: 1
scopes: ["todo"]
methods:
  GET:
    public: true
    description: "Returns all todo entries"
    responses: 
      200: Todo-Collection
      500: Message
    action: "${dir.src}/Todo/collection.php"
  POST:
    public: false
    description: "Creates a new todo entry"
    request: Todo
    responses: 
      201: Message
      500: Message
    action: "${dir.src}/Todo/insert.php"

• version: The version descibes the version of this route. If the API evolves you can define multiple versions for the same route. A user can then invoke a specific version of the endpoint.
• scopes: Assigns the route to the defined scopes. Scopes are used to give users only access to specific endpoints. In this example a user needs to have access to the “todo” scope to post new todo entries.
• methods: This lists all available request methods. The endpoint returns a 405 Method Not Allowed in case the method is not availabe.
• public: Indicates whether the endpoint is public or private. In case the endpoint is private a user needs to provide an access token (which also has the fitting scopes assigned) to access the method.
• description: A general description what this method does. It is also used in various API specification formats i.e. OpenAPI to describe the API more in detail.
• request: Contains the name of a JSON Schema which describes the request body JSON format. If a user sends data to the endpoint the request data must be valid according to the provided schema.
• responses: Contains a JSON Schema for each response code which describes the response body JSON format. Should contain for each possible status code a fitting schema or at least for the success response.
• action: The action describes a script or url which is called on request. The action executes then the endpoint logic and produces the fitting response.

Then we need to define a JSON Schema which describes the structure of our Todo entity. This schema is also referenced in the route definition. We could use i.e. the following JSON schema (resources/schema/todo/entity.json):

{
  "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"]
}

In order to connect in your action to a remote service i.e. a database you need to configure a connection (resources/connections.yaml):

Mysql-1:
  class: Fusio\Adapter\Sql\Connection\Sql
  config:
    type: "pdo_mysql"
    host: "${env.MYSQL_1_HOST}"
    username: "${env.MYSQL_1_USER}"
    password: "${env.MYSQL_1_PW}"
    database: "${env.MYSQL_1_DB}"

This “Mysql-1” connection gives us the possibility to execute SQL statments against the configured databases. You need to enter the fitting credentials into the “.env” file.

Then we need to implement the logic to return i.e. all todo entries. Therefor we create a file (src/Todo/collection.php) which contains the following code:

In this action we access the “Mysql-1” connection and simply select all entries from the “app_todo” table.

Then we need to create file (src/Todo/insert.php) in order to insert new todo entries:

In this action we also use the “Mysql-1” connection to create a new todo entry.

Now we are done! We have defined our route, added a JSON schema and implemented the endpoint logic. To deploy this API we simply need to execute the following command:

php bin/fusio deploy

With these simple steps we have a build an API which is easy to maintian and extend and has also all features of a modern API like i.e.:

• Authorization (OAuth2)
• Rate limiting
• Logging
• Analytics
• Specification (OpenAPI)

You can access the API backend at the “/fusio” endpoint. Through the Fusio backend panel you can control your API.

Fusio comes also with the Swagger-UI app which shows the automatically generated OpenAPI specification.

I hope this article helps you to implement a great API solution. For more information please visit the website of Fusio.