Skip to content
  • Documentation >
  • API >
  • REST API >
  • Extending REST API >
  • Adding custom media type

Adding custom media type

In this example case, you pass a new media type in the Accept header of a GET request to /content/locations/{locationPath} route and its controller action (Controller/Location::loadLocation).

By default, this resource takes an application/vnd.ez.api.Location+xml (or +json) Accept header. The following example adds the handling of a new media type application/app.api.Location+xml (or +json) Accept header to obtain a different response using the same controller.

You need the following elements: * A ValueObjectVisitor to create the new response corresponding to the new media type; * A ValueObjectVisitorDispatcher to have this ValueObjectVisitor used to visit the default controller result; * An Output\Visitor service associating this new ValueObjectVisitorDispatcher with the new media type.

Note

You can change the vendor name (from default vnd.ez.api to new app.api like in this example), or you can create a new media type in the default vendor (like vnd.ez.api.Greeting in the Creating a new REST resource example). To do so, tag your new ValueObjectVisitor with ezpublish_rest.output.value_object_visitor to add it to the existing ValueObjectVisitorDispatcher, and a new one will not be needed. This way, the media-type attribute is also easier to create, because the default Output\Generator uses this default vendor. This example presents creating a new vendor as a good practice, to highlight that this is custom extensions that isn't available in a regular Ibexa DXP installation.

New RestLocation ValueObjectVisitor

The controller action returns a Values\RestLocation object wrapped in Values\CachedValue. The new ValueObjectVisitor has to visit Values\RestLocation to prepare the new Response.

To be accepted by the ValueObjectVisitorDispatcher, all new ValueObjectVisitor need to extend the abstract class Output\ValueObjectVisitor. In this example, this new ValueObjectVisitor extends the built-in RestLocation visitor to reuse it. This way, the abstract class is implicitly inherited.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?php declare(strict_types=1);

namespace App\Rest\ValueObjectVisitor;

use eZ\Publish\API\Repository\URLAliasService;
use EzSystems\EzPlatformRest\Output\Generator;
use EzSystems\EzPlatformRest\Output\Visitor;
use EzSystems\EzPlatformRest\Server\Output\ValueObjectVisitor\RestLocation as BaseRestLocation;
use EzSystems\EzPlatformRest\Server\Values\URLAliasRefList;

class RestLocation extends BaseRestLocation
{
    private $urlAliasService;

    public function __construct(URLAliasService $urlAliasService)
    {
        $this->urlAliasService = $urlAliasService;
    }

    public function visit(Visitor $visitor, Generator $generator, $data)
    {
        // Not using $generator->startObjectElement to not have the XML Generator adding its own media-type attribute with the default vendor
        $generator->startHashElement('Location');
        $generator->attribute(
            'media-type',
            'application/app.api.Location+' . strtolower((new \ReflectionClass($generator))->getShortName())
        );
        $generator->attribute(
            'href',
            $this->router->generate(
                'ezpublish_rest_loadLocation',
                ['locationPath' => trim($data->location->pathString, '/')]
            )
        );
        parent::visit($visitor, $generator, $data);
        $visitor->visitValueObject(new URLAliasRefList(array_merge(
            $this->urlAliasService->listLocationAliases($data->location, false),
            $this->urlAliasService->listLocationAliases($data->location, true)
        ), $this->router->generate(
            'ezpublish_rest_listLocationURLAliases',
            ['locationPath' => trim($data->location->pathString, '/')]
        )));
        $generator->endHashElement('Location');
    }
}

This new ValueObjectVisitor receives a new tag app.rest.output.value_object.visitor to be associated to the new ValueObjectVisitorDispatcher in the next step. This tag has a type property to associate the new ValueObjectVisitor with the type of value is made for.

1
2
3
4
5
6
7
8
9
services:
    #…
    App\Rest\ValueObjectVisitor\RestLocation:
        class: App\Rest\ValueObjectVisitor\RestLocation
        parent: ezpublish_rest.output.value_object_visitor.base
        arguments:
            $urlAliasService:  '@ezpublish.api.service.url_alias'
        tags:
            - { name: app.rest.output.value_object.visitor, type: EzSystems\EzPlatformRest\Server\Values\RestLocation }

New ValueObjectVisitorDispatcher

The new ValueObjectVisitorDispatcher receives the ValueObjectVisitors tagged app.rest.output.value_object.visitor. As not all value FQCNs are handled, the new ValueObjectVisitorDispatcher also receives the default one as a fallback.

1
2
3
4
5
6
7
services:
    #…
    App\Rest\Output\ValueObjectVisitorDispatcher:
        class: App\Rest\Output\ValueObjectVisitorDispatcher
        arguments:
            - !tagged_iterator { tag: 'app.rest.output.value_object.visitor', index_by: 'type' }
            - '@ezpublish_rest.output.value_object_visitor.dispatcher'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<?php declare(strict_types=1);

namespace App\Rest\Output;

use EzSystems\EzPlatformRest\Output\Generator;
use EzSystems\EzPlatformRest\Output\ValueObjectVisitorDispatcher as BaseValueObjectVisitorDispatcher;
use EzSystems\EzPlatformRest\Output\Visitor;

class ValueObjectVisitorDispatcher extends BaseValueObjectVisitorDispatcher
{
    private $visitors;

    private $valueObjectVisitorDispatcher;

    private $outputVisitor;

    private $outputGenerator;

    public function __construct(iterable $visitors, BaseValueObjectVisitorDispatcher $valueObjectVisitorDispatcher)
    {
        $this->visitors = [];
        foreach ($visitors as $type => $visitor) {
            $this->visitors[$type] = $visitor;
        }
        $this->valueObjectVisitorDispatcher = $valueObjectVisitorDispatcher;
    }

    public function setOutputVisitor(Visitor $outputVisitor)
    {
        $this->outputVisitor = $outputVisitor;
        $this->valueObjectVisitorDispatcher->setOutputVisitor($outputVisitor);
    }

    public function setOutputGenerator(Generator $outputGenerator)
    {
        $this->outputGenerator = $outputGenerator;
        $this->valueObjectVisitorDispatcher->setOutputGenerator($outputGenerator);
    }

    public function visit($data)
    {
        $className = get_class($data);
        if (isset($this->visitors[$className])) {
            return $this->visitors[$className]->visit($this->outputVisitor, $this->outputGenerator, $data);
        }

        return $this->valueObjectVisitorDispatcher->visit($data);
    }
}

New Output\Visitor service

The following new pair of Ouput\Visitor entries associates Accept headers starting with application/app.api. to the new ValueObjectVisitorDispatcher for both XML and JSON. A priority is set higher than other ezpublish_rest.output.visitor tagged built-in services.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
parameters:
    #…
    app.rest.output.visitor.xml.regexps: ['(^application/app\.api\.[A-Za-z]+\+xml$)']
    app.rest.output.visitor.json.regexps: ['(^application/app\.api\.[A-Za-z]+\+json$)']

services:
    #…
    app.rest.output.visitor.xml:
        class: '%ezpublish_rest.output.visitor.class%'
        arguments:
            - '@ezpublish_rest.output.generator.xml'
            - '@App\Rest\Output\ValueObjectVisitorDispatcher'
        tags:
            - { name: ezpublish_rest.output.visitor, regexps: app.rest.output.visitor.xml.regexps, priority: 20 }

    app.rest.output.visitor.json:
        class: '%ezpublish_rest.output.visitor.class%'
        arguments:
            - '@ezpublish_rest.output.generator.json'
            - '@App\Rest\Output\ValueObjectVisitorDispatcher'
        tags:
            - { name: ezpublish_rest.output.visitor, regexps: app.rest.output.visitor.json.regexps, priority: 20 }

Testing the new media-type

In the following example, curl and diff commands are used to compare the default media type (application/vnd.ez.api.Location+xml) with the new application/app.api.Location+xml.

1
2
3
diff --ignore-space-change \
  <(curl --silent https://api.example.com/api/ezp/v2/content/locations/1/2) \
  <(curl --silent https://api.example.com/api/ezp/v2/content/locations/1/2 --header 'Accept: application/app.api.Location+xml');

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
2c2,3
< <Location media-type="application/vnd.ez.api.Location+xml" href="/api/ezp/v2/content/locations/1/2">
---
> <Location media-type="application/app.api.Location+xml" href="/api/ezp/v2/content/locations/1/2">
>  <Location media-type="application/vnd.ez.api.Location+xml" href="/api/ezp/v2/content/locations/1/2">
37a39,42
>  </Location>
>  <UrlAliasRefList media-type="application/vnd.ez.api.UrlAliasRefList+xml" href="/api/ezp/v2/content/locations/1/2/urlaliases">
>   <UrlAlias media-type="application/vnd.ez.api.UrlAlias+xml" href="/api/ezp/v2/content/urlaliases/0-d41d8cd98f00b204e9800998ecf8427e"/>
>  </UrlAliasRefList>