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
andversion-history
are registered link relation types (i.e. registered with and accepted by the IANA). So that meansdelete-form
andrevision
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 makelink_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
- Update
NodeViewController
(after #2282029: Automate link relationship headers for all entity types, not just nodes it'll beEntityViewController
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. - Update
@EntityType
annotations to use this URI as the key forlinks
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
Comment #2
dawehnerWell, 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.
Comment #3
Wim LeersSorry, issue queue archeology can make one cranky.
Comment #4
Wim LeersComment #5
Wim LeersComment #7
xjmThis 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!
Comment #8
xjmOr, 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.