Problem/Motivation

This is a problem introduced in #1970360: Entities should define URI templates and standard links and #2019123: Use the same canonical URI paths as for HTML routes.

I discovered and explained this in #2293697-124: EntityResource POST routes all use the confusing default: use entity types' https://www.drupal.org/link-relations/create link template if available at length. Relevant portion quoted here:

This made me realize: then how can you discern registered link relation types versus extension link relation types?! We should use identify them by their name and URI respectively. That'd match the spec. So we should continue to do it like this patch is already doing: using URIs!

However… that won't work because Drupal 8 shipped with violations of this principle already, and we can't change that because it'd break BC. We should have done #2113345: Define a mechanism for custom link relationships before D8 shipped, then we wouldn't have made this mistake. For example for Node in HEAD:

 *   links = {
 *     "canonical" = "/node/{node}",
 *     "delete-form" = "/node/{node}/delete",
 *     "edit-form" = "/node/{node}/edit",
 *     "version-history" = "/node/{node}/revisions",
 *     "revision" = "/node/{node}/revisions/{node_revision}/view",
 *   }

Of those, only canonical, edit-form and version-history are registered link relation types (i.e. registered with and accepted by the IANA). So that means delete-form and revision are already extension link relation types (i.e. Drupal-specific).

(This also means that if the IANA accepts new link relation types that happen to use the same names as the ones Drupal used, but with a different meaning, that we will be forced to break BC. For D9, we should change the entity type links annotation to use URIs as keys for extension link relation types, and we should also make link_relation_types.yml use URIs as keys for those.)

[…]

In fact, @linclark predicted that the logic in the REST module would have to change depending on how #2113345: Define a mechanism for custom link relationships would be solved. See her comment at #2019123-43: Use the same canonical URI paths as for HTML routes.

Proposed resolution

  1. Update NodeViewController (after #2282029: Automate link relationship headers for all entity types, not just nodes it'll be EntityViewController that we need to update) to use the URI of an extension link relation type that #2113345: Define a mechanism for custom link relationships have now finally made available.
  2. Update @EntityType annotations to use this URI as the key for links entries. So not:
     *   links = {
     *     "canonical" = "/node/{node}",
     *     "delete-form" = "/node/{node}/delete",
    

    but:

     *   links = {
     *     "canonical" = "/node/{node}",
     *     "https://drupal.org/link-relations/delete-form" = "/node/{node}/delete",
    

Point 1 can be done now, with minimal disruption.

Point 2 can only be done in Drupal 9, it'd be too disruptive.

Remaining tasks

TBD

User interface changes

None.

API changes

TBD

Data model changes

TBD

Comments

Wim Leers created an issue. See original summary.

dawehner’s picture

Well, I personally believe that the actual problem is merging links we expose as HTTP links and stuff we just use internally is the problem. These links headers are mostly exposed to the developers when they want to link to something related to an entity: $entity->toUrl('revision-history') for example. When the HTTP links are separated we could totally achieve this, without producing problematic UX.

Please update the issue title to not make it chx like.

Wim Leers’s picture

Title: EntityType link templates are broken by design » EntityType link templates: using link relation type names as keys is a problem

Sorry, issue queue archeology can make one cranky.

Wim Leers’s picture

Issue tags: +API-First Initiative
Wim Leers’s picture

Version: 8.4.x-dev » 9.x-dev
Category: Bug report » Plan

Version: 9.x-dev » 9.0.x-dev

The 9.0.x branch will open for development soon, and the placeholder 9.x branch should no longer be used. Only issues that require a new major version should be filed against 9.0.x (for example, removing deprecated code or updating dependency major versions). New developments and disruptive changes that are allowed in a minor version should be filed against 8.9.x, and significant new features will be moved to 9.1.x at committer discretion. For more information see the Allowed changes during the Drupal 8 and 9 release cycles and the Drupal 9.0.0 release plan.

xjm’s picture

Version: 9.0.x-dev » 9.1.x-dev

This would be a minor-only change. Since 8.9.x and 9.0.x are now in beta, I'm moving this to 9.1.x. Thanks!

xjm’s picture

Or, well, major-only as written. We'd also need to find some way to provide some BC layer, shim, something for minor backport for the continuous upgrade path.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.