extensions.md

Extensions

Extensions allow your API to support additional functionality that is not part of the base specification.

Defining Extensions

Extensions can be defined by extending the Tobyz\JsonApiServer\Extension\Extension class and implementing two methods: uri and handle.

You must return your extension's unique URI from uri.

For every request that includes your extension in the media type, the handle method will be called. If your extension is able to handle the request, it should return a PSR-7 response. Otherwise, return null to let the normal handling of the request take place.

use Psr\Http\Message\ResponseInterface;
use Tobyz\JsonApiServer\Context\Context;
use Tobyz\JsonApiServer\Extension\Extension;

use function Tobyz\JsonApiServer\json_api_response;

class MyExtension extends Extension
{
    public function uri(): string
    {
        return 'https://example.org/my-extension';
    }

    public function handle(Context $context): ?ResponseInterface
    {
        if ($context->path() === 'my-extension') {
            return json_api_response([
                'my-extension:greeting' => 'Hello world!',
            ]);
        }

        return null;
    }
}

::: warning
The current implementation of extensions has no support for augmentation of standard API responses. This API may change dramatically in the future. Please create an issue if you have a specific use-case you want to achieve.
:::

Registering Extensions

Extensions can be registered on your API server using the extension method:

use Tobyz\JsonApiServer\JsonApi;

$api = new JsonApi();

$api->extension(new MyExtension());

The API server will automatically perform appropriate content negotiation and activate the specified extensions on each request.

Atomic Operations

An implementation of the Atomic Operations extension is available at Tobyz\JsonApi\Extension\Atomic.

When using this extension, you are responsible for wrapping the $api->handle call in a transaction to ensure any database (or other) operations performed are actually atomic in nature. For example, in Laravel:

use Illuminate\Support\Facades\DB;
use Tobyz\JsonApiServer\Extension\Atomic;
use Tobyz\JsonApiServer\JsonApi;

$api = new JsonApi();

$api->extension(new Atomic());

return DB::transaction(fn() => $api->handle($request));