Rework to improve and simplify identifiers management

[soyuka]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	yes
Tickets	adaptation of #3664 with proper depreciation also fixes api-platform/api-platform#1518 and others
License	MIT
Doc PR	TBD

Move logic of identifiers extractor upwards, use only identifier converter downwards

TODO:

• fix tests
• open another PR that deprecates plain identifiers in favor of a documented normalizer
• Document the work to be done on 3.0

When removing deprecations on 3.0 we should:

• rename IdentifierDenormalizer to IdentifierConverter
• remove the use of the symfony DenormalizerInterface for Identifier/Normalizers as their job is slightly different from normalizers in which they just convert the type from string to integer, boolean etc.
• remove IdentifiersExtractor from IriConverter and every data provider that may use it.
• remove IdentifierConverterInterface::HAS_IDENTIFIER_CONVERTER

The diff at https://github.com/api-platform/core/pull/3664/files can be used as a reference.

[soyuka]

This will change with the rework of the subresources

[bendavies]

@soyuka this broke custom identifiers, InvalidIdentifierException is now thrown in OperationDataProviderTrait::extractIdentifiers.
example, which works on 2.5.9, but broken on 2.6.0 beta1

/**
 * @ApiResource(
 *     itemOperations={
 *         "get": {
 *             "method": "GET",
 *             "path": "/customers/{id}"
 *         }
 *     }
 * )
 */
Class Customer
{
    /**
     * @ApiProperty(identifier=false)
     *
     * @ORM\Id
     * @ORM\Column(type="uuid")
     * @ORM\GeneratedValue(strategy="NONE")
     */
    protected UuidInterface $id;

    /**
     * @ApiProperty(identifier=true)
     *
     * @ORM\Column(type="string")
     */
    protected string $externalId;
}

/customers/foo won't work now.

EDIT:

changing the operation path from "path": "/customers/{id}" to "path": "/customers/{externalId}" fixes it, is this intentional or a BC break?

[soyuka]

@bendaviesthe change is intentional I've taken great care to try and make the change as soft as possible. I may have forgotten something here. What you can do is:

/**
 * @ApiResource(
 *     itemOperations={
 *         "get": {
 *             "method": "GET",
 *             "path": "/customers/{id}",
 *             "identifiers": {"id": {Customer::class, "externalId"}}
 *         }
 *     }
 * )
 */
Class Customer
{
    /**
     * @ApiProperty(identifier=false)
     *
     * @ORM\Id
     * @ORM\Column(type="uuid")
     * @ORM\GeneratedValue(strategy="NONE")
     */
    protected UuidInterface $id;

    /**
     * @ApiProperty(identifier=true)
     *
     * @ORM\Column(type="string")
     */
    protected string $externalId;
}

Did it at least throw an error helping you fix it?

[bendavies]

@soyuka yes, this error was thrown:

core/src/DataProvider/OperationDataProviderTrait.php

Line 117 in 5000965

throw new InvalidIdentifierException(sprintf('Parameter "%s" not found', $parameterName));

thanks for the code sample using identifers. i fixed it using "path": "/customers/{externalId}" but yours seems nicer!

[bendavies]

hm what if i remove my path completely? will that work too?
i notice your identifiers configuration isn't covered here: https://api-platform.com/docs/core/identifiers/#identifiers

[soyuka]

Yes removing the path should work!

Indeed identifiers are not documented yet I need to find some time, in the meantime you can use https://github.com/api-platform/core/blob/master/docs/adr/0001-resource-identifiers.md as reference.

[tiavina-mika]

    /**
     * @ORM\Column(type="string", length=255)
     * @ApiProperty(identifier=true)
     */
    private $slug;

works fine.

But what if I need both id and slug as identifiers?
For exemple, I want both endpoints

• /api/articles/{id}
• /api/articles/slug/{slug}