Hi. I love API Platform and would like to use it on a commercial project.

However, there is one major flaw I found while experimenting with it 😢 there is no reasonable mechanism to add metadata to collection responses.

The hydra standard allows for arbitrary metada on collections. I tried all possible approaches over a week...

Recommended solution

Currently, it is recommended to compose/decorate a Normalizer, e.g.

// CustomCollectionNormalizer.php

//...
public function normalize(mixed $object, string $format = null, array $context = []): array
{
    return array_merge(
        $this->normalizer->normalize($object, $format, $context), // returns a hydra:collection
        ['custom_metadata' => $this->objectNormalizer->normalize(
            new LargeAndComplexDTO::from($arrayOfMetadata), // e.g. Elasticsearch Aggregations
            $format,
        )]
    );
}

Problems:

❌ metadata are invisible in the Responses section of the endpoint documentation
❌ DTOs of metadata do not have a Schema generated

In order for the documentation to work properly, you have to:

1. manually construct a schema and an example value for the metadata (e.g. decorate and modify - in a very complex way - at least SchemaFactory, OpenApiFactory etc) so that an "Example response" corresponds with actual response schema.
2. annotate the DTO of metadata with a "fake" ApiResource and expose no operations on it, so that the DTO is recognized in the "Schema" section of the docs.
3. Risk that whenever someone modifies the metadata DTO, they will forget to update the docs accordingly as well 👎

Ideal solution

Allow to implement a custom collection, e.g. CustomPaginator that can contain other properties.

#[GetCollection(
    provider:  CollectionProvider, // built-in or custom, doesn't matter
    output: ItemDTO::class, // optionally, hydrate a DTO instead of an entity
    collectionOutput: CustomPaginator::class, // pass the hydrated entities/DTOs to a custom collection instance
)]

The custom paginator needs to conform to the PaginatorInterface, but can define arbitrary properties. The items are passed into it using something like a new, PaginatedItemsInterface:

class CustomPaginator implements \IteratorAggregate, PaginatorInterface, PaginatedItemsInterface
{
     // ...

    public readonly CustomMetadataDTO $metadata,

    // ...

    // Dictated by PaginatedItemsInterface, called when `collectionOutput: CustomPaginator::class` is specified
    public function setItems(array $items): void
    {
        // e.g. $this->items = $items; store and/or modify the items somehow
    }
}

The remaining piece of puzzle - some mechanism needs to serialize the Paginator, generate the schema&docs, ...

Rather than manually serializing the collection, as happens now in multiple places:

Instead:

1. create a built-in strategy for each format (jsonld, json etc) that adds the hydra:*** annotations for jsonld, completely ignores metadata for json, etc.
2. introspects any additional public properties/getters (metadata) on the custom paginator, correctly builds its schema for the docs (jsonld) or ignores the metadata completely (json), ...

Example of the final outcome

Facet search built with ElasticSearch:

Schema for the Example response docs is automatically generated:

{
  "hydra:member": ["..."],
  "hydra:totalItems": 15,
  "hydra:view": {
    "@id": "string",
    "type": "string",
    "hydra:first": "string",
    "hydra:last": "string",
    "hydra:previous": "string",
    "hydra:next": "string"
  },
  "hydra:search": {
    "@type": "string",
    "hydra:template": "string",
    "hydra:variableRepresentation": "string",
    "hydra:mapping": [
      {
        "@type": "string",
        "variable": "string",
        "property": "string",
        "required": true
      }
    ]
  },
  "facets": {
    "@context": "string",
    "@id": "string",
    "@type": "string",
    "company": [
      {
        "@context": "string",
        "@id": "string",
        "@type": "string",
        "name": "string",
        "items": 0
      }
    ]
  }
}

Actual response is properly built with correct IRIs for metadata as well:

{
  "@context": "/api/contexts/SearchOffer",
  "@id": "/api/search_offers",
  "@type": "hydra:Collection",
  "hydra:totalItems": 1,
  "hydra:member": ["..."],
  "hydra:view": {
    "@id": "/api/search_offers?fulltext=php",
    "@type": "hydra:PartialCollectionView"
  },
  "hydra:search": {
    "@type": "hydra:IriTemplate",
    "hydra:template": "/api/search_offers{?fulltext}",
    "hydra:variableRepresentation": "BasicRepresentation",
    "hydra:mapping": [
      {
        "@type": "IriTemplateMapping",
        "variable": "fulltext",
        "property": "fulltext",
        "required": false
      }
    ]
  },
  "facets": {
    "@type": "SearchOfferFacets",
    "@id": "/api/.well-known/genid/9b3baf0ebba142588980",
    "company": [
      {
        "@type": "FacetBucket",
        "@id": "/api/.well-known/genid/ce2d0b1399b413efbf67",
        "name": "Microsoft",
        "items": 15
      }
    ]
  }
}