36991 support showlinks in the content drive search api apiv1drivesearch

[nicobytes]

This pull request enhances the pagination and retrieval of menu links in the Content Drive browser API. It introduces independent, cursor-based paging for menu links (in addition to folders and contentlets), ensuring more consistent and scalable navigation when browsing assets under a folder. The changes also unify how links are mapped and returned, improving both API clarity and client-side handling.

Pagination and API enhancements:

• Added independent cursor-based pagination for menu links, alongside folders and contentlets, in the getPaginatedContents method of BrowserAPIImpl, including new fields (linkCursor, linkCount, hasMoreLinks, nextLinkCursor) in both the request (BrowserQuery) and response (PaginatedContents). [1] [2] [3] [4] [5] [6] [7] [8]

• Modified the documentation and method contracts in both BrowserAPI and BrowserAPIImpl to describe the new paging behavior for links, clarifying the contract for clients and the order in which page slots are filled (folders, then links, then contentlets). [1] [2]

Link retrieval and mapping improvements:

• Implemented the linksDefaultView method to retrieve, filter, and deterministically order menu links directly under a parent, supporting stable paging and matching legacy endpoint behavior.

• Standardized link mapping in API responses by using a shared constant for the MIME type and providing additional metadata (permissions, owner name, etc.) in the returned map, aligning with folder conventions. [1] [2]

Supporting changes:

• Added necessary imports for new functionality, including Stream and UserLocalManagerUtil. [1] [2] [3]

These updates collectively provide a more robust, flexible, and user-friendly API for browsing assets, especially when dealing with large numbers of menu links.

#36991

Fixes #36991

[Copilot]

Pull request overview

Adds opt-in support for returning menu Links from the Content Drive Search API (POST /api/v1/drive/search) by treating links as a third paginated source alongside folders and contentlets.

Changes:

• Introduces showLinks (default false) and linkCursor request fields, and threads linkCursor through BrowserQuery.
• Extends BrowserAPIImpl.getPaginatedContents() to page links independently (with linkCount/hasMoreLinks/nextLinkCursor) and merge them into the response list.
• Adds automated coverage via Postman collection updates and a new integration test suite entry.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
dotCMS/src/main/java/com/dotcms/rest/api/v1/drive/ContentDriveHelper.java	Enables showLinks/linkCursor support when building the BrowserQuery for drive search and logs link-related info.
dotCMS/src/main/java/com/dotcms/rest/api/v1/drive/AbstractDriveRequestForm.java	Adds request contract/documentation for showLinks and linkCursor.
dotCMS/src/main/java/com/dotcms/browser/BrowserQuery.java	Adds linkCursor to the query object + builder and includes it in toString().
dotCMS/src/main/java/com/dotcms/browser/BrowserAPIImpl.java	Implements link paging + response metadata, and adds link-to-drive map transformations.
dotCMS/src/main/java/com/dotcms/browser/BrowserAPI.java	Updates Javadoc to reflect multi-source cursor pagination (folders/links/contentlets).
dotcms-postman/src/main/resources/postman/ContentDriveResource.postman_collection.json	Adds Postman tests covering showLinks flag behavior and link cursor contract.
dotcms-integration/src/test/java/com/dotcms/rest/api/v1/drive/ContentDriveLinksTest.java	New integration test validating opt-in behavior, permissions, paging, suppression rules, ordering, and legacy parity.
dotcms-integration/src/test/java/com/dotcms/MainSuite3a.java	Registers the new integration test in the main suite.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[claude]

Claude finished @nicobytes's task in 2m 30s —— View job

---

Code Review

Reviewed the diff against origin/main — the link-paging logic in BrowserAPIImpl, the new FolderAPI.getLiveLinks(Host, …) overload, the BrowserQuery/form/helper wiring, and the cursor clamping.

New Issues

No issues found.

I traced the paths that usually break in this kind of change and each one is sound:

• Budget exhaustion → empty link slice. When folders consume the whole budget, maxResults == 0, so linkEnd = min(linkStart, totalLinks) = linkStart, the slice is empty, nextLinkCursor stays put and hasMoreLinks still reports the remainder (BrowserAPIImpl.java:1741-1749). Matches testFoldersFillingPageStillReportsMoreLinks.
• Negative cursor → subList(-1, …) 500. All three cursors and offset are now Math.max(0, …) in BrowserQuery.Builder (BrowserQuery.java:433-457, 469-471), so hostile input clamps instead of throwing.
• live:true cross join. getLinks now delegates the live case to FolderAPI.getLiveLinks (the correlating live_inode = links_1_.inode branch) rather than passing working=false (BrowserAPIImpl.java:205-227). The new getLiveLinks(Host, …) mirrors the existing Folder overload — READ check, cond.live=true; cond.deleted=false, filterCollection (FolderAPIImpl.java:1329-1343).
• Permission filtering. Links are READ-filtered by getLinks/getLiveLinks and again per-link via getPermissionIdsFromRoles(...).contains(READ) before exposure — no over-exposure path. Owner/permission-name mapping mirrors DotFolderTransformerImpl (incl. UserLocalManagerUtil), so the "parity with folders" claim holds.
• Map shape. link.getMap() sets title = getTitle(), and driveLinkView sets name = getTitle() and strips inode — consistent with the shape testLinkMapUsesContentDriveShape asserts.
• Constructor fan-out. The widened PaginatedContents constructor has a single caller (BrowserAPIImpl.java:1774), so no stale call sites.

The earlier review threads (cursor clamp, getLiveLinks refactor, @AfterClass teardown, title-filter and live:true tests, userSearchable Javadoc) are all reflected in the current diff. The two open PaginationUtil / DB-pagination threads are design questions, not defects — the author's reasoning (REST-layer-only util; DotConnect doesn't paginate in-DB; post-filter slicing needed for correctness) checks out against the code.

One non-blocking observation, explicitly not flagged as a bug: driveLinkView issues a hasLiveVersion + getPermissionIdsFromRoles call per link, so a folder near the documented 1000-link ceiling does ~N DB round-trips. This is parity with the existing per-item folder/contentlet view path, and the ceiling is already documented in linksDefaultView's Javadoc, so it's consistent with the codebase rather than a regression.
· nicobytes/36991-support-showlinks-in-the-content-drive-search-api-apiv1drivesearch

[nicobytes]

How to use showLinks — API contract and examples

Two new fields on the request, three on the response. Everything else is unchanged.

Request

Field	Type	Default	Purpose
showLinks	boolean	false	Include the menu Links directly under assetPath
linkCursor	int	0	Index to start paging links from

The false default is what keeps every current consumer (Content Drive, AssetPicker) behaving exactly as it does today.

Response

{
  "entity": {
    "list": [ /* folders, links and contentlets merged, ordered by sortBy */ ],
    "folderCount": 2,  "hasMoreFolders": false, "nextFolderCursor": 2,
    "linkCount": 3,    "hasMoreLinks": true,    "nextLinkCursor": 3,
    "contentCount": 0, "hasMoreContent": true,  "nextContentCursor": 0
  },
  "errors": [], "messages": [], "i18nMessagesMap": {}
}

Links are a third symmetric pagination source: their own cursor, count and hasMore flag, mirroring the folder slice.

---

1. Basic — links alongside everything else

curl -u admin@dotcms.com:admin \
  -X POST 'http://localhost:8080/api/v1/drive/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "assetPath": "//demo.dotcms.com/about-us/",
    "showLinks": true,
    "maxResults": 20
  }'

2. The redirect_custom_field_new.vtl case — links + pages

This is the direct translation of the legacy browser flags that motivated the issue:

curl -u admin@dotcms.com:admin \
  -X POST 'http://localhost:8080/api/v1/drive/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "assetPath": "//demo.dotcms.com/",
    "showLinks": true,
    "baseTypes": ["HTMLPAGE"],
    "showFolders": false,
    "live": true,
    "archived": false,
    "sortBy": "modDate:desc",
    "maxResults": 20
  }'

3. Links only

Links are not a BaseContentType, so showLinks is orthogonal to baseTypes. An empty baseTypes array disables the content query:

curl -u admin@dotcms.com:admin \
  -X POST 'http://localhost:8080/api/v1/drive/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "assetPath": "//demo.dotcms.com/about-us/",
    "showLinks": true,
    "showFolders": false,
    "baseTypes": [],
    "maxResults": 20
  }'

The three documented outcomes:

Request	Result
showLinks: true, baseTypes omitted	links plus content of every base type
showLinks: true, baseTypes: ["HTMLPAGE"]	links plus pages
showLinks: true, baseTypes: [], showFolders: false	links only

4. Paging links to exhaustion

Feed nextLinkCursor back as linkCursor and keep offset at 0:

# page 1
curl -u admin@dotcms.com:admin -X POST 'http://localhost:8080/api/v1/drive/search' \
  -H 'Content-Type: application/json' \
  -d '{"assetPath":"//demo.dotcms.com/about-us/","showLinks":true,
       "showFolders":false,"baseTypes":[],"maxResults":2,"linkCursor":0}'
# -> linkCount: 2, hasMoreLinks: true, nextLinkCursor: 2

# page 2
curl ... -d '{... "maxResults":2, "linkCursor":2}'

Stop when hasMoreLinks: false; from then on send showLinks: false to skip the query entirely.

Budget order is folders -> links -> contentlets. If folders fill maxResults, you get linkCount: 0 with hasMoreLinks: true and an unadvanced nextLinkCursor — that is the signal that links remain, not a bug.

---

Link shape

Identify links by mimeType === "application/dotlink" (or type === "links").

{
  "identifier": "9f2c...",
  "type": "links",
  "title": "Contact Us Redirect",
  "name": "Contact Us Redirect",
  "mimeType": "application/dotlink",
  "extension": "link",
  "__icon__": "linkIcon",
  "url": "www.google.com",
  "protocol": "https://",
  "target": "_blank",
  "linkType": "EXTERNAL",
  "permissions": ["READ", "WRITE"],
  "modDate": "2026-08-19T17:41:28.000Z",
  "owner": "Admin User"
}

Note two Content Drive conventions, consistent with the folders this endpoint already returns: no inode, and permissions as role-type names rather than raw integer ids. The legacy includeLinks() used by /api/v1/browser is untouched.

Three filters suppress links

Sending showLinks: true together with any of these yields linkCount: 0, because a Link cannot satisfy them:

• mimeTypes — a Link has no file MIME type
• workflow — a Link carries no workflow state (folders are already dropped here for the same reason)
• userSearchable — resolves against a single content type; a Link has no fields

Two inherited limits

Both match legacy /api/v1/browser behaviour, which is what the AC asked for:

• Links are direct children only of the resolved assetPath — no recursion into subfolders, even at site root (where contentlets are gathered recursively).
• filters.text matches link titles only, applied in memory, because links are not indexed in Elasticsearch.

[nicobytes]

Review feedback addressed — 725c224d14

Thanks @oidacra, this was a good catch list. One of the five turned out to be a genuine blocker, so the headline first.

live:true + showLinks:true was returning duplicates

Thread #discussion_r3815730314 was right, and worse than stated. FolderFactoryImpl.getChildrenClass appends the version table to the FROM list with no join predicate of its own; the only correlation it ever produces is the incidental one from working_inode = links_1_.inode. Passing showWorking straight through meant working=false flipped that to <>, which correlates nothing and degenerates into a cross product.

Reproduced: five links came back 35 times for live:true, archived:false. A second run returned 20 — the multiplier is the installation's link-version count.

That is the one combination the motivating consumer actually sends: redirect_custom_field_new.vtl passes showWorking: false, which the drive maps to live: true. The feature was broken in the use case that prompted #36991.

BrowserAPIImpl.getLinks now always asks FolderAPI for the working links and resolves "live" by keeping the ones carrying a published version. BrowserQuery ORs showArchived into showWorking, so only live:true, archived:false changes behaviour — the default and archived:true already passed working=true. Since getLinks(BrowserQuery) is shared with includeLinks, legacy /api/v1/browser with showWorking:false is fixed too; calling that out explicitly as it is outside this PR's stated scope.

The factory itself is untouched, so any other caller passing working=false still hits the cross join. Filed as #37133 with the SQL, the reproduction and the one-line fix — it needs its own PR because getChildrenClass is shared by Link and Contentlet, and correcting working=false also changes its semantics.

Everything else

Thread	Outcome
Negative cursor → 500	Clamped contentCursor, folderCursor, linkCursor and offset at zero in BrowserQuery.Builder, matching the clamp maxResults already does there. Fixes the pre-existing folder/offset cases too.
sortBy vs pre-slice order	Documented, per your own reading — folders and contentlets slice the same way, so AC9 holds by consistency. Noted in both showLinks() and PaginatedContents.
Missing @AfterClass	Added, mirroring ContentDriveKeywordSearchTest.cleanup(). The permission test's site, role and user are hoisted into statics so they are torn down too.
Untested title filter	Three cases added, including the upper-cased term for the toLowerCase() branch. The filterFolders asymmetry is intentional and now documented.
Copilot: userSearchable in Javadoc	Already fixed in 243523a29b.

Test evidence

ContentDriveLinksTest is 14 → 18 tests, all green. The four new ones were confirmed failing against the pre-fix code:

testLiveOnlyReturnsPublishedLinks              AssertionError: expected:<35> but was:<5>
testLinksHonourLiveAndArchivedLikeLegacyBrowser AssertionError: expected:<35> but was:<5>
testNegativeLinkCursorIsTreatedAsZero          IndexOutOfBoundsException: fromIndex = -1

Worth noting why the existing live/archived test could not have caught this: it collapsed ids into a HashSet, which erases duplicates by construction, and asserted parity against the legacy path, which shares the defect. Both halves had to change — it now compares lists with an explicit no-duplicates assertion.

Postman got two more requests (filters.text and live:true), but weaker ones by necessity: menu links cannot be created over REST, so that collection has no link fixtures and can only pin that the combinations are accepted and the contract survives. Said so in the request descriptions.

On AC10 (openapi.yaml)

Nothing to commit, and that is correct rather than an omission: ContentDriveResource.search is @Hidden, so /v1/drive has no generated schema at all. The single showLinks in the yaml belongs to BrowserQueryForm (the legacy browser), untouched here. Verified with ./mvnw compile -pl :dotcms-core — the file comes back unchanged.

[nicobytes]

Second review round — 9a32593948

Three new threads, from @freddyDOTCMS and @jcastro-dotcms. All architectural rather than defects. I verified each one against the code before answering: one was right and produced a code change; two don't hold, and I've put the evidence in the threads. Net effect is that the PR gets smaller.

@jcastro-dotcms — right, and the method already existed

The hasLiveVersion filter I'd put in BrowserAPIImpl was a workaround in the wrong layer. FolderAPI.getLiveLinks(Folder, User, boolean) already existed with the correct SQL (cond.live=true → live_inode = links_1_.inode, the correlating = branch — no cross join). The only gap was the Host overload.

• Added FolderAPI/FolderAPIImpl.getLiveLinks(Host, User, boolean).
• BrowserAPIImpl.getLinks now picks between getLinks and getLiveLinks; the in-memory filter and the javadoc paragraph explaining the workaround are both deleted.

ContentDriveLinksTest is untouched and still 18/18 green. I didn't adjust a single assertion, so the suite passing is a statement that behaviour is preserved rather than that I re-fitted the tests. One behavioural difference declared in the thread: getLiveLinks returns the live version rows, where the old code returned the working rows of links that have a live version. For live:true the new one is the more correct answer.

@freddyDOTCMS — PaginationUtil

Not applicable at this layer. Of the 25 new PaginationUtil(...) sites in dotCMS/src/main/java, all 25 are under com.dotcms.rest.* — no business-layer *APIImpl uses it. It imports JAX-RS + Servlet types and writes X-Pagination-* headers; all five getPage overloads are @Deprecated, and the replacement NPEs without a request/response. Beyond the layer: Paginator<T> is one source with one totalResults, while this block runs three sources against one decrementing budget and returns nine pagination scalars; and it derives its offset from a page number, so it can't take three cursors.

I did flag the adjacent point that I think is genuinely worth discussing: ContentDriveResource returns ResponseEntityView rather than ResponseEntityPaginatedDataView, so drive responses carry no pagination envelope or X-Pagination-* headers. That's a real conversation about the resource's response shape — but it changes the /api/v1/drive/search contract that's already on main with consumers, so not for a showLinks PR.

@freddyDOTCMS — pagination in the DB query

The premise doesn't hold: DotConnect doesn't paginate in the database. statement.setMaxRows is commented out (DotConnect:698), startRow is a client-side rs.next() skip (:790), and the limit is a client-side loop bound (:797). Passing offset/limit through getChildrenClass would satisfy the wording while changing nothing in the DB — I wasn't willing to make that change and report it as done.

Real SQL LIMIT/OFFSET wouldn't be correct either: four filters shrink the set after the query (READ filterCollection, live, the in-memory title filter since links aren't in ES, and the per-link getPermissionIdsFromRoles), so a page of 40 could return 3 with hasMoreLinks: false. And permissions can't move into the WHERE clause — permission_reference is a lazily, asynchronously populated cache, so a join there would omit readable links.

The codebase has already decided this twice in writing — FolderAPIImpl.searchFolders:812 ("no LIMIT — pagination happens in Java so that permission filtering does not produce short pages") and BrowserAPIImpl:184. Folders do the same in-memory slice today; the link branch mirrors them line for line.

The real limitation inside that question, which I'd rather name than let my "no" bury: the convenience overloads of getChildrenClass hardcode a 1000-row ceiling on an unordered result set, so a folder with >1000 links truncates non-deterministically. It's documented in linksDefaultView's javadoc. Fixing it means a searchLinks(...) method modelled on searchFolders, not SQL paging — happy to file that if it's worth queueing.

---

I resolved @jcastro-dotcms's thread since it's actioned, and left both of @freddyDOTCMS's open on purpose — they were questions, and a declined objection isn't mine to close. Push back if you disagree with either reading.