API normalisaton and duplicate: /api/folders/${folderId}/listing vs /api/folders/{id}/resources

[EdouardVanbelle]

I saw that you optimized /api/folders/${folderId}/listing,
this API was not partcial to use because it returns it's own format which is not FileDto nor FolderDto, answers lack informations and cannot be sorted due to group by folder, files
it is currently still used

So I mark it deprecated and implemented a normalized API: /api/folders/{id}/resources with a cursor and sorting
returns contains directly the FileDto and FolderDto format

To ease frontend implementation, all other routes are now using the same format /api/favorites/{id}/resources, /api/trash/resources, etc

What about removing deprecated routes and have a uniform API
So focus on performance will be only on normalized API

any opinion @DioCrafts ?

[DioCrafts]

Thanks for pushing on this @EdouardVanbelle — fully agree with the direction. A normalized, cursor + sortable /resources API returning real FileDto/FolderDto is the right contract, and converging on it removes a lot of duplicate listing logic. 👍

I audited the deprecated surface before cutting anything. Findings:

• The bundled SvelteKit frontend has already migrated favorites/recent/trash/grants to /resources (shared fetchResourcePage helper).
• Of the six deprecated old-format endpoints, five have no remaining consumer at all — not the SvelteKit frontend, not the legacy /static frontend, and no WebDAV/CalDAV/CardDAV/WOPI/mobile surface. The Nextcloud OCS/trashbin handlers call the service layer directly (trash_service.get_trash_items, fav_svc.get_favorites), not these HTTP routes.

So I removed those five in #501 (Phase 1):

Removed	Replacement
GET /api/folders/{id}/contents	GET /api/folders/{id}/resources
GET /api/folders/{id}/contents/paginated	GET /api/folders/{id}/resources
GET /api/favorites	GET /api/favorites/resources
GET /api/recent	GET /api/recent/resources
GET /api/trash	GET /api/trash/resources

Handlers, routes, OpenAPI registrations and the now-dead list_folder_contents{,_paginated}_impl helpers are gone; the underlying service methods stay (Nextcloud needs them). clippy -D warnings clean, 443 unit tests green, OpenAPI regenerates without the five paths.

The one I did not remove: GET /api/folders/{id}/listing

This one isn't just duplicate cruft — it's the Files view's primary data path and currently does things /resources doesn't:

• ETag + real 304 Not Modified conditional caching (the frontend runs stale-while-revalidate on it — instant repaint, then revalidate; no re-render on 304).
• Server-computed favorite_ids / shared_ids badge sets in the same response, scoped to the on-screen items — this is exactly the N+1 the endpoint was built to eliminate.
• Grouped {folders, files} with full path/drive_id.

/resources today is a flat cursor array with no ETag/304, no badge sets (the DTOs have no is_favorite/is_shared), and it deliberately blanks folder path/drive_id (it was designed for share recipients who must not see hierarchy). So swapping the Files view onto it as-is would regress the most-used screen.

Proposed Phase 2 (separate PR)

Before retiring /listing, bring /resources to parity for the owner-browsing case:

1. add favorite_ids/shared_ids (or per-item is_favorite/is_shared) to the folder /resources response,
2. add ETag + If-None-Match/304 support,
3. don't blank path/drive_id when the caller owns the tree,
4. migrate the Files view + MoveDialog to it, then delete /listing.

That gets us to the fully uniform API you're after, with performance work focused on the single path — without a regression in the interim. Happy to take Phase 2 next, or if you'd rather own it (it's your initiative), I'm glad to review. Thanks again!

[EdouardVanbelle]

no dependency with Oxicloud-desktop ? :)
I guess you will soon deprecate /api/uploads in favor or /api/files/delta

[EdouardVanbelle]

@DioCrafts note that I did not touch GET /api/photos it already has a cursor and metadata added
I let you check if it worth normalizing into /api/photos/resources (metadata also possible), group/order by possible (geo, etc)