IRI of entities with custom controller contain route/path information

[joerndyherrn]

API Platform version(s) affected: 3.1.9

Description
Operations with a custom controller return entities with iris that match the uriTemplate.

How to reproduce
I got the following api resource:

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/substitutes/substituting',
            controller: SubstitutingApiController::class,
            normalizationContext: ['groups' => ['substituting_get']],
            name: 'substitutes_substituting',
        ),
        new Get(
            uriTemplate: '/substitutes/{id}/token',
            controller: SubstitutingTokenApiController::class,
            normalizationContext: ['groups' => ['substituting_get']],
            name: 'substitutes_substituting_token'
        ),
        new GetCollection(),
        new Get(),
    ])]

When caling /api/substitutes/substituting it will return a entity Substitute with @id: "/api/substitutes/0cbd07c8-e4e7-11ed-876f-b4af5186afd8/token" but should return @id: "/api/substitutes/0cbd07c8-e4e7-11ed-876f-b4af5186afd8"

When changing the order of the operations to have the following:

#[ApiResource(
    operations: [
        new GetCollection(),
        new Get(),
        new GetCollection(
            uriTemplate: '/substitutes/substituting',
            controller: SubstitutingApiController::class,
            normalizationContext: ['groups' => ['substituting_get']],
            name: 'substitutes_substituting',
        ),
        new Get(
            uriTemplate: '/substitutes/{id}/token',
            controller: SubstitutingTokenApiController::class,
            normalizationContext: ['groups' => ['substituting_get']],
            name: 'substitutes_substituting_token'
        ),
    ])]

For the default get and get collection operations it will generate correct iri. But now /api/substitutes/substituting is not callable as it tries to find an entity with id substituting

Possible Solution
When having the last tested order of operations - get collections with a fixeduriTemplate should be callable and not refer to the default get operation.
Another possible solution would be to fix iri generation to exclude any route information.

[joerndyherrn]

I think the main issue is when using the second example and getting - 404 Not found as it tries to find an entity with substituting as id

[joerndyherrn]

With the following decorator I achieve the desired behaviour:

<?php

namespace App\Decorator;

use ApiPlatform\Api\IriConverterInterface;
use ApiPlatform\Api\UrlGeneratorInterface;
use ApiPlatform\Exception\InvalidArgumentException;
use ApiPlatform\Metadata\CollectionOperationInterface;
use ApiPlatform\Metadata\Operation;
use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
use ApiPlatform\Util\ResourceClassInfoTrait;
use function is_string;

class IriConverterDecorator implements IriConverterInterface
{
    use ResourceClassInfoTrait;

    /**
     * @param IriConverterInterface                      $iriConverter
     * @param ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory
     */
    public function __construct(
        protected IriConverterInterface                      $iriConverter,
        protected ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory,
    )
    {
    }

    /**
     * @inheritdoc
     */
    public function getResourceFromIri(string $iri, array $context = [], ?Operation $operation = null)
    {
        return $this->iriConverter->getResourceFromIri($iri, $context, $operation);
    }

    /**
     * @inheritdoc
     */
    public function getIriFromResource($resource, int $referenceType = UrlGeneratorInterface::ABS_PATH, ?Operation $operation = null, array $context = []): ?string
    {
        try {
            $resourceClass = is_string($resource) ? $resource : $this->getResourceClass($resource, true);
        } catch (InvalidArgumentException $exception) {
            return null;
        }

        $forceCollection = $operation instanceof CollectionOperationInterface;
        $operation       = $this->resourceMetadataCollectionFactory->create($resourceClass)->getOperation(null, $forceCollection, true);
        $iri             = $this->iriConverter->getIriFromResource($resource, $referenceType, $operation, $context);

        return $iri;
    }
}

[soyuka]

would it work to specify the operation you want to use to compute the IRI? something like:

#[GetCollection(itemUriTemplate: '/substitutes/{id}')

api-platform/api-platform#2422

[rubobaquero]

Hello @soyuka ,

Same thing happens when defining a specific route for a Patch operation. Example:

        new Patch(
            uriTemplate: '/purchases/{id}/billing-address',
            uriVariables: [
                'id' => new Link(fromClass: self::class),
            ]
        ),

The answer to that request contains the wrong @id parameter. It returns /api/purchases/1/delivery-date and as far as I understand should be /api/purchases/1, that is the IRI of the entity.

{
	"@context": "\/api\/contexts\/Purchase",
	"@id": "\/api\/purchases\/1\/delivery-date",
        ....
}

In this case, we can't apply the solution itemUriTemplate: '/purchases/{id}', because its not available in Patch Operations.

[SherinBloemendaal]

I'm facing a similar issue like @rubobaquero , we've some custom PATCH calls and the IRI's are based on the uriTemplate of the custom PATCH call instead of the default GET call.

Edit:
To solve it, you can create a custom processor, instead of returning the data you can manually serialize it to jsonld.

[loconox]

This unwanted behavior is due to the way api plateform handles the generation of iri.

• First it retrieves the resource metadata
• Next it tries to get the operation getOperation function of ResourceMetadataCollection with $operationName null and $forceCollection to true in case of collection operation false otherwise. It's false in our use case
• Finally the getOperation returns the first operation get item or get collection depending of the flag

In case we declare custom item or collection operation it could make those operations to be catch.
I think a mechanism to declare which operation if the default get item or get collection could fix this. I can propose a PR.

[loconox]

The itemUriTemplate works great to specify, during the normalization of a collection operation, what item operation should be used to produce iri for each item. I think we could extend this behavior to the resource scope by defining a defaultItemUriTemplate at resource level. What do you think of that ?