Provide links to resource versions (entity revisions)

Initial patch to add revision links. This patch depends on #2992833: Add a version negotiation to revisionable resource types. Added combined patch here.

Blocking on #2992833: Add a version negotiation to revisionable resource types.

Stand-alone patch here.

Now that the plugin issue is back to green, let's get this re-tested.

This patch will add links to the collections as well.

There was a missing use statement.

I'd also like to see working-copy-of, which should appear for non-default revision normalizations.

This adapts the patch to the latest state of #2992833: Add a version negotiation to revisionable resource types.

Now that #2992833: Add a version negotiation to revisionable resource types is RTBC, let's move this forward again! 💪

#2992833: Add a version negotiation to revisionable resource types landed! Let's do this now :)

I'd sort of like this to wait for #2995960: Add a Link and LinkCollection class to support RFC8288 web linking.. Any opposed?

Not opposed, but slightly concerned since that could take a while. But with 2.0 out, hopefully we can make significant progress there :)

#3022584: Consolidate and simplify NormalizerValue objects: introduce CacheableNormalization landed, which unblocked #2995960: Add a Link and LinkCollection class to support RFC8288 web linking..

#2995960: Add a Link and LinkCollection class to support RFC8288 web linking. landed!

#2995960: Add a Link and LinkCollection class to support RFC8288 web linking. landed and added the LinkCollection class which I wanted to be used to add these links. However, it did not actually make use of LinkCollections on the resource object level. #3015438: Wrap entity objects in a ResourceObject which carries a ResourceType will accomplish that.

Currently scrutinizing #3015438: Wrap entity objects in a ResourceObject which carries a ResourceType prior to commit. I wanted to be absolutely certain that this issue is indeed not only possible thanks to that other issue, but also significantly simpler in terms of code. I'm happy to report that this turns out to be true! In #12, we had to modify both the entity normalization and the top-level document normalization — even though both were for entities. Thanks to #3015438, we'll only have to make additions in one place. It also helps validate #2994193: [META] The Last Link: A Hypermedia Story :)

#3015438: Wrap entity objects in a ResourceObject which carries a ResourceType landed.

SUPER pleased to see how simple this is now :D

Just a couple thoughts:

1. +++ b/src/JsonApiResource/ResourceObject.php
   @@ -71,9 +73,17 @@ class ResourceObject implements CacheableDependencyInterface, ResourceIdentifier
   +      $self_url = Url::fromRoute(Routes::getRouteName($this->getResourceType(), 'individual'), ['entity' => $this->getId()]);
   

   I think the self links should be ?resourceVersion=rel:{vid} if the resource type is versionable.

2. +++ b/src/JsonApiResource/ResourceObject.php
   @@ -71,9 +73,17 @@ class ResourceObject implements CacheableDependencyInterface, ResourceIdentifier
   +        $latest_version_url = $self_url->setOption('query', [JsonApiSpec::VERSION_QUERY_PARAMETER => 'rel:' . VersionByRel::LATEST_VERSION]);
   +        $this->links = $this->links->withLink(VersionByRel::LATEST_VERSION, new Link(new CacheableMetadata(), $latest_version_url, [VersionByRel::LATEST_VERSION]));
   +        $working_copy_url = $self_url->setOption('query', [JsonApiSpec::VERSION_QUERY_PARAMETER => 'rel:' . VersionByRel::WORKING_COPY]);
   +        $this->links = $this->links->withLink(VersionByRel::WORKING_COPY, new Link(new CacheableMetadata(), $working_copy_url, [VersionByRel::WORKING_COPY]));
   

   These should only appear if this particular version is not the latest version or working copy.

#30: be my guest to make that happen :) I'm glad the tests are catching the changes in JSON:API responses!

1. ✅ But why by ID, and why not latest-version? I think because it allows the client to track server-side changes more easily, but I'd like us to document this explicitly.
2. ✅

#32:

1. Yes, and to easily disambiguate resource objects in #3009588: Provide a collection resource where a version history can be obtained (`version-history`, `predecessor-version` and `successor-version` link relations).
2. 😗👌

I'll push this over the finish line tomorrow.

Okay, this should apply the appropriate expectations for resource object links (self, working-copy and latest-version).

In doing this I realized that we probably also need to update the self and related links under relationship objects. A relationship self link is essentially a URI for that relationship object. If a relationship differs between revisions, we don't want the relationship object on an individual response to be different from the result if the link is followed.

Let's add tests for those.

I don't want this next bit to block this issue because this issue has already sat for too long... but I do want to plant this seed now:

I didn't expect these links to be added within the ResourceObject class. I was hoping we would use this issue to pilot a more public API for LinkCollections (but keep it internal until we were satisfied with it).

I envisioned either a tagged service or plugin called a "link provider". It would be passed a LinkCollection object. In this issue, we would have implemented that service/plugin within the Revisions namespace (meaning all revision stuff was completely contained in that space). E.g.:

namespace Drupal\jsonapi\Revisions;

/**
 * @internal
 */
class RevisionsLinkProvider {

  public function alterLinks(LinkCollection $links) {
    $context = $links->getContext();
    if ($context instanceof ResourceObject && $context->getResourceType()->isVersionable()) {
      // add/update `self`, `latest-version` and/or `working-copy` links.
    }
    elseif ($context instanceof Relationship && $context->getRelationshipContext()->getResourceType()->isVersionable()) {
      //update `self` and `related` links. The `Relationship` ^ object does not exist yet.
    }
    return $links;
  }

}

While I hate to make another prerequisite here, I think #3033473: Clean-up: Remove LinkManager is super close and will make this change a go a little smoother. It will also avoid having to reroll the change completely and will be more conceptually similar to what I showed in #35.

After we get this green, we can mark it Postponed, in the mean time, I'll keep them in sync as necessary.

Whoops, missed one variable rename.

#3033473: Clean-up: Remove LinkManager landed!

This should be green 🤞

Looks 😍