Api Platform conference
Register now
API Platform Conference
September 19-20, 2024 | Lille & online

The international conference on the API Platform Framework

API Platform Conference 2024: meet the best PHP, JavaScript and API experts

Learn more about the event, register for the conference, and get ready for two days of inspiration, ideas, and knowledge-sharing with our incredible lineup of renowned specialists and advocates.

Register now

Customize HTTP Cache Tags

This guide describes how to customize HTTP Cache Tags included in the API response header by registering a TagCollector service. In this example, the Id of a resource will be used to generate the cache tag instead of its IRI. If you only want to add additional tags without changing them, it might be sufficient to follow the standard documentation on http cache. First, we need our book resource. For the sake of this example, we assume the id to be unique across all resources (otherwise replacing the IRI with Id would make no sense).
// src/App/ApiResource.php
namespace App\ApiResource;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Operation;
    operations: [
        new Get(provider: Book::class.'::provide'),
class Book
    #[ApiProperty(identifier: true)]
    public string $id = "unique-id-1";
    public static function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
        return (new self());
Now, we define our TagCollector service. Check the PHPDoc in TagCollectorInterface to see the various information, which is available within $context. Add any tags you want to be included in the response to $context['resources'].
// src/App/Service.php
namespace App\Service;
use ApiPlatform\Serializer\TagCollectorInterface;
use App\ApiResource\Book;
class TagCollector implements TagCollectorInterface
    public function collect(array $context = []): void 
        if (isset($context['property_metadata'])) {
        $iri = $context['iri'] ?? null;
        $object = $context['object'] ?? null;
        if ($object && $object instanceof Book) {
            $iri = $object->id;
        if (!$iri) {
        $context['resources'][$iri] = $iri;
Replace the service ‘api_platform.http_cache.tag_collector’ with your new TagCollector class.
// src/App/DependencyInjection.php
namespace App\DependencyInjection;
use App\Service\TagCollector;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
function configure(ContainerConfigurator $configurator): void
    $services = $configurator->services();
    $services->set('api_platform.http_cache.tag_collector', TagCollector::class);
Request the book. When using Swagger UI, you should see that your ‘Cache-Tags’ header now includes the Id only instead of the full Iri.
// src/App/Playground.php
namespace App\Playground;
use Symfony\Component\HttpFoundation\Request;
function request(): Request
    return Request::create('/books/unique-id-1.jsonld', 'GET');
…or verify directly in testing.
// src/App/Tests.php
namespace App\Tests;
use ApiPlatform\Playground\Test\TestGuideTrait;
use ApiPlatform\Symfony\Bundle\Test\ApiTestCase;
final class BookTest extends ApiTestCase
    use TestGuideTrait;
    public function testAsAnonymousICanAccessTheDocumentation(): void
        $response = static::createClient()->request('GET', '/books/unique-id-1.jsonld');
        $this->assertResponseHeaderSame('Cache-Tags', 'unique-id-1');
            '@id' => '/books/unique-id-1',
            '@type' => 'Book',
            'id' => 'unique-id-1',
If you rely on invalidation from Api-Platform, don’t forget that you’d also need to have your own implementation of PurgeHttpCacheListener. Otherwise the wrong tags will be purged.

You can also help us improve this guide.

Made with love by

Les-Tilleuls.coop can help you design and develop your APIs and web projects, and train your teams in API Platform, Symfony, Next.js, Kubernetes and a wide range of other technologies.

Learn more

Copyright © 2023 Kévin Dunglas

Sponsored by Les-Tilleuls.coop