4.0.3 breaks BC on error handling: hydra prefixes missing

[j-schumann]

API Platform version(s) affected: 4.0.3, 3.4.2

Description
In 4.0.3 + 3.4.2 the "hydra:" prefix was removed from error responses (in https://github.com/api-platform/core/pull/6624/commits/7d23c76fd13e2283af95e9aefc5540a1bc86215a). This breaks error handling in our clients in multiple APIP projects as they read hydra:description

How to reproduce
APIP works in 4.0.2 -> update api-platform/state|validator to 4.0.3 without any other change -> hydra properties disappear

Possible Solution
a) Revert this "fix", it is a BC break which should not occur in a patch/minor version, especially not without previous deprecation or changelog note (in 4.0.3) b) Add an option to keep the prefix, as I would expect serializer: hydra_prefix: true to behave. This option should be enabled by default (else BC break)

Additional Context
I don't know why this breaking change was introduced in 3.4.2, it was known to be breaking as it was noted in the Changelog:

Hydra prefix on errors is breaking, read title not hydra:title. The hydra_prefix flag doesn't apply to errors as it provided redundant information (both hydra:title and title were available)

This note should also have been on the 4.0.3 changelog as this was the first 4.x version that introduced that break. (At least it would have saved me half an hour debugging as nothing in the changelog indicated that the reason could be this version.)

I am not the only one relying on those response fields: https://github.com/api-platform/core/issues/5963#issuecomment-1808497808

[soyuka]

In 3.4: Using rfc_7807_compliant_errors: true (extra_properties => default) you keep the prefix right? In 4.x this breaks and you don't have these prefixes anymore on errors. We had so much going on that it was hard to think about everything and 4.0.3 has a bug fix as in 4.x these prefixes should've been removed. Indeed, hydra_prefix has no incidence on errors, I'll try to find a way to add this behavior it may mitigate the BC break.

[soyuka]

I hope my patch fixes your issue, I'll release by Friday

[burned42]

I just tested the 4.0.4 release and for me this issue seems to be fixed and in error responses the title and description with hydra prefix are back when using hydra_prefix: true :+1: Thanks :)

[j-schumann]

For me it is working only partially: The prefix is restored (with hydra_prefix: true) only for hydra:description, hydra:title. But not for the @type.

Tests fail with:

--- Expected
+++ Actual
@@ @@
-  '@type' => 'hydra:Error',
+  '@type' => 'Error',

[j-schumann]

@soyuka When can we expect a 4.x release for that fix? As 3.4.4 including it is out since 3 days. Thanks in advance.

[soyuka]

Was just tagged

[j-schumann]

Ok, I will wait then for the release. Currently I only see tag 4.0.5 without a release, and the changelog does not include the fix.

[soyuka]

we usually don't bring up changes from lower branches into the CHANGELOG as they're already documented with the lower version tag. Github releases does that though and we often clean them up. Not sure what's best :shrug:

[burned42]

Of course that's just my perspective, but as a user of version 4 of the package, I usually don't follow the changelog for version 3 anymore, but I rather check for news of the major version I'm using.

So if it's even extra work to remove those changes from the changelog, no objections from my side to just leave them in. :)

[j-schumann]

but as a user of version 4 of the package, I usually don't follow the changelog for version 3 anymore, but I rather check for news of the major version I'm using.

This is the same for me, not all projects can merge fixes from lower branches into higher ones, or don't do that at the same time. So for someone not following the development closely it is hard to see if a fix like https://github.com/api-platform/core/pull/6721, that was first merged into a lower branch, has already been merged up and is contained within the next release of the higher version branch. So in most cases it is not necessary to read the changelog of previous major versions to find out what was changed/fixed. Or to put it shorter: The changelog for a specific version should contain every fix that was made/merged the first time in that major version.

Symfony does this, e.g. here https://github.com/symfony/messenger/releases: v7.1.3 + v7.0.10 + v6.4.10 + v5.4.42 all contain the same bugfix in their changelog. It would really be appreciated if APIP could follow this too :)

I will close this issue now as the fix is released in 4.0.5 and working, thanks @soyuka