Create an endpoint for getting all menu elements for a single menu

I started working on this in the issue fork linked above. Rather than invent our own format, I've been prototyping the endpoint using Linkset draft as the format for a use case #1. It has not been adopted as an RFC, but it has been picked up by the IETF's HTTP API working group and I expect it to be adopted without too many changes. Since this is technically a contrib module, I think working from a draft is fine for the time being. This is actually an nice opportunity to contribute outside the Drupal ecosystem and the internet more broadly.

If we use this draft, we could make a JavaScript library for it that would be useful outside of the Drupal ecosystem, just like the once library 🙂

You can see exactly what the endpoint is expected to look like in the tests. This is what I have so far:

1. Route: /system/menu/{menu}/linkset
   • {menu} is a parameter for a menu config entity's machine name.
   • Example output

Gonna do a self-review, but would appreciate a first pass from another reviewer too :)

Thanks for trying it out @Deciphered! I really appreciate it!

Not being JSON:API seems inconsistent with the existing decoupled architecture of Drupal, and will require a seperate client for consumption.

I don't think we need/should make media type-specific clients. Let's just make code that works with Drupal. A Drupal client can use application/vnd.api+json for resources, application/schema+json for schema, and application/linkset+json for link sets (e.g. menus).

JSON:API 1.1-RC3 has support for JSON Schema integration via the describedby link. So it's not unprecedented to use mixed formats for mixed purposes with JSON:API (so long as it's all JSON).

There doesn't appear to be any way to filter the results, or get additional data.

I think both of these go beyond the scope of this issue. Beyond this issue, I think a JSON-RPC plugin makes the most sense for these kinds of things.

The data structure was a bit odd, with both the linkset and linkset[#].item[#]['drupal-menu'] providing arrays of objects.

The format is entirely driven by https://tools.ietf.org/html/draft-ietf-httpapi-linkset-00.

The linkset being an array makes me think that it's possible to get multiple linksets from a single endpoint, for translation support or similar.

This initially confused me too. There is no way to represent multiple linksets. From my understanding, the reason for the top array is to support different anchors within a single linkset. The drupal-menu array is required by the draft. Specifically, it says: The value of an extension attribute MUST be represented by an array, even if there only is one value to be represented.

The absence of a unique ID per link is also a problem for me. In my case I constructed an ID using the menu name and the hierarchy.

I plan on writing a little JS today to denormalize the linkset representation into something more easily consumable. Mind if I ping you to give it a whirl?

- /system/menu/main/linkset only returns the English results
- /es/system/menu/main/linkset only returns the Spanish results.

That's awesome! I didn't intend this, it's just a consequence of using the menu tree loader, I think.

I don't care very much about the hierarchy idea. We can convert it to a parent/child representation if y'all feel very strongly about it for aesthetic reasons. I agree that it is less shocking, but I want to make sure we understand that it has some real drawbacks in terms of ease of use and response size.

For example, these two bits of pseudocode contain equivalent information:

[{
  "href": "/foo",
  "hierarchy": ".000"
}, {
  "href": "/bar",
  "hierarchy": ".000.000"
}, {
  "href": "/baz",
  "hierarchy": ".000.000.000"
}, {
  "href": "/qux",
  "hierarchy": ".000.000.001"
}]

[{
  "href": "/foo",
  "id": "foo",
  "parent": null,
  "weight": 0
}, {
  "href": "/bar",
  "id": "bar",
  "parent": "foo",
  "weight": 0
}, {
  "href": "/baz",
  "id": "baz",
  "parent": "bar",
  "weight": 0
}, {
  "href": "/qux",
  "id": "qux",
  "parent": "bar",
  "weight": 1
}]

If you have a parent property, then every object must also have an id because you must have an ID to reference. Therefore, we will have to invent IDs, or expose the link plugin IDs. This is more verbose and I was trying to avoid that because it exposes implementation details, like which modules are installed.

Using plugin IDs will also encourage clients to hardcode IDs. For example, if we supply the plugin ID user.logout, clients will be tempted to filter and hardcode something against it. I didn't want to promote that pattern since I would like to promote link relations for these kinds of things in the future. In that particular example, the user.logout link is actually the login link if you're not authenticated. That would be confusing!

Note that while not explicitly an ID, `${drupal-menu.name}:${drupal-menu.hierarchy}` does form a unique value if you need one for some reason, like @Deciphered discovered at the end of #7.

If you have a parent property, then you must also have a weight property (if you want to be explicit about order).

Now, some code examples showing how easy the value is to work with:

Get subtree of "/bar":

links.filter(link => link.hierarchy.startsWith(bar.hierarchy));

Get direct parent of "/qux":

const getParent = (link) => link.hierarchy.slice(0, link.hierarchy.lastIndexOf('.'));
links.find(link => link.hierarchy === getParent(qux));

Get grandparent of "/qux":

const getParent = (link) => link.hierarchy.slice(0, link.hierarchy.lastIndexOf('.'));
links.find(link => link.hierarchy === getParent(getParent(qux)));

Get links with max depth 2:

links.filter(link => (link.hierarchy.split('.').length - 1) === 2);

Is some link a descendant of another link?

link.hierarchy.startsWith(other.hierarchy);

Rebased on top of #3202608: Remove the original implementation code so that we can run tests on Drupal CI.

I think this is ready to go.

Thanks for the review @nod_! I created a follow up for that issue.