Valvoıd.
search hotlink icon profile hotlink icon

Basic Custom API Example

This page explains the basic steps for creating a custom API that extends Fusion. The example builds on the basic extender package example, so it assumes that you have already implemented that setup. For the complete result of this example, see the GitLab repository. Note that this repository contains content for other examples as well, as the documentation uses a single package for all examples.

Additionally, for real-world examples and potential workloads, refer to Fusion's default APIs located in the /src/Hub/APIs directory.

On This Page

Source Code

The relative root for all the directories within this section is the extension group within the custom source code files directory.

API

To maintain consistency with the original package, it is recommended to follow the existing implementation pattern within stackable extension. Create the directory /Hub/Remote/Custom and add the Custom.php file with the following content: 

                <?php

namespace Valvoid\Fusion\Valvoid\Package\Hub\Remote\Custom;

use Valvoid\Fusion\Hub\APIs\Remote\Remote;
use Valvoid\Fusion\Hub\APIs\Remote\Status;
use Valvoid\Fusion\Hub\Responses\Remote\References;

class Custom extends Remote
{
    public function getReferencesUrl(string $path): string
    {
        return $this->config["url"] . "$path/versions";
    }

    public function getReferencesOptions(): array
    {
        return [];
    }

    public function getStatus(int $code, array $headers): Status
    {
    }

    public function getReferences(string $path, array $headers, array $content): References
    {
    }

    public function getFileUrl(string $path, string $reference, string $file): string
    {
    }

    public function getFileOptions(): array
    {
    }

    public function getArchiveUrl(string $path, string $reference): string
    {
    }

    public function getArchiveOptions(): array
    {
    }

    public function getRateLimitReset(array $headers, string $content): int
    {
    }

    public function getErrorMessage(int $code, array $headers, string $content): string
    {
    }
}

Note that the namespace prefix Valvoid\Fusion\Valvoid\Package consists of segments from two package identifiers. It starts with the origin package identifier, allowing Fusion to inflate the custom code, and it ends with extender identifier to prevent conflicts in case of multiple extensions.

In the root directory of the nested Fusion package, execute the inflate command: 

                php fusion inflate

After running the command, the cached lazy.php file located in the /cache/loadable directory, relative to the nested Fusion package root, will contain the custom API along with the default entries: 

                // Auto-generated by Fusion package manager. 
// Do not modify.
return [
    'Valvoid\Fusion\Valvoid\Package\Hub\Remote\Custom\Custom' => '/extensions/src/valvoid/package/Hub/Remote/Custom/Custom.php',
    // another entries
    // ...
];

The custom API is now loadable and can be added to the config. If required, optionally you can validate and manipulate the config for your API. To do so, inside the custom API directory /Hub/Remote/Custom, create the /Config directory and add at least one of the following config files:

Interpreter

Create the optional Interpreter.php file with the following content:

                <?php

namespace Valvoid\Fusion\Valvoid\Package\Hub\Remote\Custom\Config;

use Valvoid\Fusion\Config\Interpreter as ConfigInterpreter;

class Interpreter extends ConfigInterpreter
{
    public static function interpret(array $breadcrumb, mixed $entry): void
    {
    }
}

To make this file loadable, execute the inflate command again: 

                php fusion inflate

The interpreter is the first file that gets called. It validates the static config to ensure that the parser and normalizer can handle it. In this case, it does nothing.

Parser

Create the optional Parser.php file with the following content: 

                <?php

namespace Valvoid\Fusion\Valvoid\Package\Hub\Remote\Custom\Config;

use Valvoid\Fusion\Config\Parser as ConfigParser;

class Parser extends ConfigParser
{
    public static function parse(array $breadcrumb, array &$config): void
    {
    }
}

To make this file loadable, execute the inflate command again: 

                php fusion inflate

The parser is the file that gets called after the interpreter. It prepares entries for overlay. In this case, it does nothing.

Normalizer

Create the optional Normalizer.php file with the following content: 

                <?php

namespace Valvoid\Fusion\Valvoid\Package\Hub\Remote\Custom\Config;

use Valvoid\Fusion\Config\Normalizer as ConfigNormalizer;

class Normalizer extends ConfigNormalizer
{
    public static function normalize(array $breadcrumb, array &$config): void
    {
        $config["protocol"] ??= "https";
        $config["domain"] ??= end($breadcrumb);
        $config["url"] = $config["protocol"] . "://api." .
            $config["domain"] . "/v1/registry";
    }
}

To make this file loadable, execute the inflate command again: 

                php fusion inflate

The normalizer is the last file that gets called. It finalizes the config and ensures that all necessary values are set. In this case, it provides a default url value.

Config

In the custom config files directory, create the `hub.php` file with the following content: 

                <?php

use Valvoid\Fusion\Valvoid\Package\Hub\Remote\Custom\Custom;

return [
    "hub" => [
        "apis" => [
        
            // default non-configured API
            "custom" => Custom::class
        ]
    ]
];

Metadata

Since the following step blocks the build task group, add a custom pseudo package dependency to the fusion.local.php metadata file: 

                <?php

return [
    "description" => "Basic example package!",
    "structure" => [
        "/dependencies" => [
            "custom/pseudo/package/1.0.0"
        ]
    ]
];

Execute the build command again: 

                php fusion build

The main task now result in the error: 

                Couldn't resolve host name

This error occurs because the pseudo package doesn't exist. Remove the pseudo package to unblock the build task group.