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
Nodein 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-formandversion-historyare registered link relation types (i.e. registered with and accepted by the IANA). So that meansdelete-formandrevisionare 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
linksannotation to use URIs as keys for extension link relation types, and we should also makelink_relation_types.ymluse 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 beEntityViewControllerthat 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
@EntityTypeannotations to use this URI as the key forlinksentries. 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.