Skolem IRI and HTTP cacheability

[tucksaun]

API Platform version(s) affected: 2.6 (at least) and above

Description
When using JSON-LD, API Platform automatically exposes IRIs, but it also exposes some IRIs for anonymous resources which are not stable, leading to the body content changing from one answer to the other.
This is not desirable IMHO because it makes debugging and testing harder and also this results in the ETag header value being unstable which bust HTTP caches.

Before 2.7, the IRIs generation mechanism for anonymous resources relies on spl_object_id so this could lead to the issue when the overall number or order of PHP objects changes (cache clearing or cache miss for instance).
Since 2.7, the IRI generation relies on random_bytes so the IRI for anonymous resources becomes totally unstable preventing any HTTP caching.

Maybe I missed something but trying to override the JSON-LD context is currently of no use and the only workarounds I found are:

• override ApiPlatform\JsonLd\ContextBuilder and unset the @id key manually,
• or override ApiPlatform\Symfony\Routing\SkolemIriConverter to return a constant (empty) string.

How to reproduce
Expose an API Resource with a Doctrine embedded or a value object and hit the API using JSON-LD.
You can have a look at https://github.com/tucksaun/api-platform-iri-reproducer.

Possible Solution
IIUC the JSON-LD specs, for blank nodes the @id key is only recommended and not mandatory (https://www.w3.org/TR/json-ld11/#identifying-blank-nodes), and is useful essentially if one wants to use node references to them which is not done automatically by API Platform for anonymous resources as far as I know

So one solution could be to allow disabling the addition of Skolem IRI to anonymous resources globally or per subresource.

I even consider that (if my assumption about @id not being strictly required is correct) the use case where one wants to compare anonymous resources is probably an advanced use case and as such adding IRI to anonymous resources should probably be made an opt-in option?

Additional Context
Produced output (unstable):

{
  "@context": "/contexts/Greeting",
  "@id": "/greetings/1",
  "@type": "Greeting",
  "id": 1,
  "name": "Tugdual",
  "options": {
    "@type": "Options",
    "@id": "/.well-known/genid/493e0689a8264f70af65",
    "notify": false
  },
  "foo": {
    "@type": "ValueObject",
    "@id": "/.well-known/genid/659262289b3472742a7a",
    "bar": 42
  }
}

headers (unstable):

...
etag: "753c1f46a6df1e05ae9525539d217504"
...

Desired output:

{
  "@context": "/contexts/Greeting",
  "@id": "/greetings/1",
  "@type": "Greeting",
  "id": 1,
  "name": "Tugdual",
  "options": {
    "@type": "Options",
    "notify": false
  },
  "foo": {
    "@type": "ValueObject",
    "bar": 42
  }
}

headers (stable):

...
etag: "090f00d2c63731328b6a24352e4d74d8"
...

[soyuka]

Use

    #[ApiProperty(
        types: [false]
    )]

to remove the @id.

[tucksaun]

thank you for the suggestion @soyuka 🙌
unfortunately, after some tests, it does not seem to have any impact 🙁

But I noticed that AbstractItemNormaliwer is looking at iris on the property metadata:

core/src/Serializer/AbstractItemNormalizer.php

Lines 596 to 598 in 8108899

	if (null !== ($propertyIris = $propertyMetadata->getIris())) {
	$childContext['output']['iri'] = 1 === (is_countable($propertyIris) ? \count($propertyIris) : 0) ? $propertyIris[0] : $propertyIris;
	}

so maybe you instead meant this? :

#[ApiProperty(
    iris: [false]
)]

---

Your suggestion made me go deeper into the code and I noticed that it looks like the intention is to let one override or disable the IRI somehow:

core/src/JsonLd/ContextBuilder.php

Lines 126 to 132 in 8108899

	if (!isset($context['iri']) || false !== $context['iri']) {
	if (!isset($context['iri']) && !$this->iriConverter) {
	throw new RuntimeException('Can not guess an anonymous resource IRI without IRI Converter.');
	}
	$jsonLdContext['@id'] = $context['iri'] ?? $this->iriConverter->getIriFromResource($object);
	}

But the fact is that it does not work on 3.0 because JsonLdContextTrait never transmits the context to the ContextBuilder:

core/src/JsonLd/Serializer/JsonLdContextTrait.php

Lines 53 to 59 in 8108899

	if (isset($context['jsonld_has_context'])) {
	return $contextBuilder->getAnonymousResourceContext($object, ['api_resource' => $context['api_resource'] ?? null, 'has_context' => true]);
	}
	$context['jsonld_has_context'] = true;
	return $contextBuilder->getAnonymousResourceContext($object, ['api_resource' => $context['api_resource'] ?? null]);

Should this lack of transmission of the context's output then be considered a bug?
It used to be done on 2.x but it is not the case anymore.
I tried a quick patch locally and it seems to work properly for this use case 😁
Would you be willing to accept a PR to fix this?

On 2.7 and using annotations, overriding works but not removal because using @ApiProperty(iri=false) is not possible due to type constraints.
Could this be considered a bug as well and would you accept a PR?

cheers

[soyuka]

I had that issue and had attempted to fix it, my bad I thought that it was implemented that way but in fact we didn't use it.

My proposal for now is to add a NullIriConverter that decorates ours and does something like this:

public function getIriFromResource(object|string $resource, int , int $referenceType = UrlGeneratorInterface::ABS_PATH, Operation $operation = null, array $context = []): string {
  if ($resource instanceof ValueObject) { 
    return `null`;
  }
}

I'll try to provide a patch in this way and cover the BC layer from 2.7.

[tucksaun]

fixed by #5046, closing