Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Give your feedback on use cases until Monday 22nd of Febuary
This issue is for discussing use cases, for implementation discussions, please see related issues corresponding to each use-case. What we want is feedback on the Problem/Motivation part of this issue, the Proposed resolution section is here only as a summary of the related issue to give an overview on how we're currently planning on solving this but it is not yet set in stone.
Problem/Motivation
Menus are for navigating an application. In a decoupled architecture there are multiple ways to build a navigation:
- A navigation that is global and static.
- That is, it will not change from page to page (or screen to screen a native app for example)
- A navigation(s) that changes from page to page
- Attach "Departments" menu to all "product" content types
- Attach "Content Moderator Shortcuts" menu to "moderator" role
In #1, it is probably more intuitive to have a single endpoint for "downloading" the menu.
In #2, it is probably easier to have Drupal attach/not attach the menu based on the current API response so that context can be taken into consideration.
Our solution for #1 should be very simple and/or low-friction to implement and our solution for #2 needs to be very flexible because there are so many possible features that a site builder might implement.
For #1, we believe that a single endpoint for fetching all menu items for a single menu would be easiest for a JS developer to use/implement.
For #2, we believe that attaching menus directly to responses instead of making a special endpoint with parameters to customize to provide context will be easiest to consume.
Proposed resolution
For #1 see #3189459: (use case #1) Provide an API response for "stateless menu" use case for discussions. To summarize: we will make an endpoint at the URL /{tbd}. The response will be a nested array of objects representing menu tree element items with children. Access will be controlled by checking access the the link targets.
For #2 see #3186628: (use case #2) Decide on an API response format for menu data for discussions. To summarize: we will amend JSON:API with links that are attached based on some contextual conditions. These will be representat as JSON:API links. Access will be controlled by checking access to the link targets. This will require a new configuration page/form for specifying those contextual conditions.
In both cases, we need to solve URL aliases. That is if a menu link itself targets internal:/node/42 the JS developer needs to be able to get the appropriate URL for it. Therefore, in both cases, we will serialize the menu link target with an absolute URL using the canonical path or its URL alias, if one exists.
In order to help JS developers resolve URL aliases to usable JSON content, we will solve #3028501: Enable header-based proactive content negotiation with optimizations and opt-outs available. so that the URL /my/url/alias will return a JSON:API response if the request specifies an Accept header with the value application/vnd.api+json.
Next steps
Create a module where we can add code to solve these two use cases- Create an endpoint for retrieving all menu elements for a single menu
- Get #3028501 to completion (we can supply a patch in our module's
composer.json - Figure out where those configuration pages/forms for #2 should live.
(we will replace these items with issue links as they are created)
Comments
Comment #2
nod_This issue was written between Gabriel and I. I think this will be a good way to arrive at concrete a solution for the menu data :)
Comment #3
gabesulliceI have started experimenting with solutions for #2 in a sandbox module: https://www.drupal.org/sandbox/gabesullice/3175828
I can promote this to a full project and make the initiative coordinators into maintainers. It shouldn't be too difficult to add an endpoint for #1 to it since all the hard parts of loading a menu link tree is already solved.
Comment #4
mirom commentedDo I understand #2 correctly that if I'll request node of type product, in the same response I'll get also all links out of Departments menu? Or will I receive link to list of all department menu links?
Comment #5
gabesulliceComment #6
lhockleyI tend to agree here for the most part.
One thing I would consider, though, would be to not overwrite the menu link target as it currently exists.
Doing so could introduce breaking changes to third party libraries which rely on that structure. Instead, I would add a new field for the explicit purpose of the full url. Perhaps something like
absolute_url?Comment #7
gabesulliceAll links belonging to the the "Departments" menu. Not a link to a list of links.
I think this is the simplest solution that requires the least front end complexity. It does create a larger response size, but I think we should optimize for simplicity first, then for performance.
However, I think we could eventually support the second case and make it configurable. I would like this standard to be adopted first though. It provides a mechanism to link to a "linkset", which is a link to a list of links, just like you described.
Comment #8
gabesullice@lhockley, since these will all be completely new endpoints, I'm not sure what breaking changes you're talking about. Can you explain a little bit more?
Comment #9
lhockley@gabesullice I actually thought you were talking about changing the existing JSON:API endpoints. If this is all in relation to a distinct endpoint, then I am very much in favor.
Comment #10
gabesulliceAh, yeah. Just posted my in-depth proposal for #3189459-4: (use case #1) Provide an API response for "stateless menu" use case. Hopefully that answers lots of questions.
(n.b. @nod_ and I discussed this issue summary, but we did not discuss the specifics I'm proposing over there).
Comment #11
nod_Tentative timebox for use-case, and hopefully, implementation discussion ends Monday, feb. 22nd (2 full weeks and 3 week-ends) Thanks @Gabriel for the very detailed proposals in both issues.
This issue is for use case discussion (the Problem/Motivation part of the issue summary), for implementation discussion (once the use-case is agreed upon by most people) please use the dedicated issues. The "Proposed resolution" section of the issue summary is only for reference and to help get an overall idea of the thing. Once there is consensus, we'll update the details if necessary. If possible I'd like to avoid implementation discussions in this issue (maybe if it's relevant to both use cases and it makes sense to talk about it here, go for it).
What we're after here is finding good answers as to why we need to "Add HTTP API for menu links to Drupal".
Comment #12
e0ipsoI am missing the Menus as Resource option here. Did we discard that option already? If so, I missed that conversation.
I think that a menu resource has the potential to combine #1 and #2. You can "download" the menu, and you can also link to that on the appropriate menus on each page and/or resource.
Comment #13
gabesullice@e0ipso, I think this:
and comment #7 might be the background that you're missing?
I.e. if we link to a menu, then the consumer has to follow the link to get that menu (an extra complication) rather than having it included in the response. It's not a big complication, but it's definitely a pattern that we'd need to provide some guidance around since it wouldn't be immediately apparent
It would also mean that we would have to create an endpoint with customizable parameters like
?anchor=https://www.example.com/product/2&depth=2Comment #7 was my way of saying…
However, I think there's merit to the argument:
IDK, I'm curious what your actual thoughts are 😅 I'm just trying to anticipate what you might say at this point.
Comment #14
vulcanr commentedI'd like to think that all the contextual settings to print Menu A, B and C, are being made in the app itself and not conditions made in Drupal (Depending on Content Type/URL/other).
So I'd like to see/use something more like a mix of #1 and #2, where:
From #2 we get all the menus from Drupal and from #1 there's a single endpoint to fetch the menus.
Maybe that was said for someone already but I missed it in the thread.
Comment #15
nod_It appears that you agree with the use case where we need to support menus that change based on the context (the context being a page/node/type/path/etc.)
For the technical solution I'd prefer we discuss that in the individual issues for use case #2, because how we're going to solve it is a complex discussion in itself (is the burden for visibility settings on the backend/frontend/etc.)
Comment #16
vulcanr commentedYes I totally agree with that!
Comment #17
volegerWould menu items represent their own type or will follow some general interface? Is would be possible to pass the content of the fields of the menu_link_content itself?
Comment #18
nod_I think the 22nd is finished in most timezones.
We appear to agree on the 2 use cases, meaning we can start working towards documenting use case #1 and continue the discussion for the use-case #2 implementation in their respective issues.
would be great to link to the survey data here when we have that on hand :)
Comment #24
nod_That's a wrap :) I updated the project page to put the use cases we are going to work on.
I wasn't in all the discussions so if I forgot a credit, ping me so I can fix that :)