Problem/Motivation
Link templates on entity types allows the definition of permanent relationships for entities of that type. In #2113345: Define a mechanism for custom link relationships this was expanded to potentially include ad hoc relationships, seeded with IANA relationships. Such relationships are fantastic for developers and for building hypermedia APIs. However, core currently supports only a single URI template per relationship.
In practice, HTTP Link headers and HAL link entries both make a special point of accepting multiple URLs, because for many of these relationships there is not a unique, single URL that represents the only instance of that relation.
- Belongs to multiple collections for it's multiple topics.
- References multiple specifications for DTD and JSON-schema descriptions of the entity type
- Composite "remix" work derived from multiple sources
- Games with next & previous relationships for a choose-your-own adventure
- Language-specific variants for, well, anything.
Part of how multiple URIs are differentiated is support in LINK headers for Target Attributes (RFC 5988 which brings in "hreflang", "media", "title", "title*", "type" for a start, but does not limit it to those. The same properties are supported in HAL links. It should be considered whether expanding to support multiple links might instead be interpreted as expanded to support a general broader range of the link specification.
Proposed resolution
As an alternative to the current annotation:
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",
}
we might alternatively support any relationship to somehow reference a multi-dimensional array, indicating the more complete version of link templates at play and preserving backwards compatibility.
Remaining tasks
Discuss if this should be pursued.
User interface changes
None.
API changes
Potential changes to link template declaration for entities.
Data model changes
None.
Comments
Comment #2
dawehnerThank you for creating the issue!
Comment #4
Wim LeersHah, actually, I needed exactly this in #2878463: [PP-1] Define a JSON API link relation for entities! I need it for the JSON API "related" and "relationships", both of which can have many URLs.
Unfortunately, to make this happen, we'd also need to change
\Drupal\Core\Entity\Entity::toUrl()
. Which is definitely a BC break.So I don't see how we can do this before D9 without introducing a parallel API, i.e. yet another way to generate a URL for entities. Perhaps a new
getLinks()
method, combined with disallowing$entity->toUrl('some-relationship-that-returns-multiple-urls')
?Comment #5
Wim LeersQuoting myself from #2878463-9: [PP-1] Define a JSON API link relation for entities:
Comment #8
geek-merlinWhat about something like
and then
Entity::toUrl('canonical')
andEntity::toUrl('canonical:uuid')
will return a string, while something likeEntity::toUrl('canonical*')
does magick and returns a string array. Won't win us a design price but hey, pure API addition.Comment #16
andypostIs it still makes sense?