[GH-ISSUE #682] Add a JSON stat/metadata endpoint for a specific file or directory path #1092

New Issue

zhus · 2026-04-09T17:16:37+03:00

zhus commented

2026-04-09 17:16:37 +03:00

Originally created by @jgoedeke on GitHub (Apr 9, 2026).
Original GitHub issue: https://github.com/sigoden/dufs/issues/682

Summary

Please add a way to query metadata for a single file or directory path and get a JSON response, without having to list the parent directory and filter client-side.

Current behavior

Right now, the JSON API seems to be listing-oriented:

?json returns directory contents as a paths array
to get metadata for one specific path, I have to:
1. request the parent directory
2. parse the JSON response
3. filter for the entry I want

This works, but it is awkward and inefficient, especially for large directories.

Desired behavior

Support a direct "stat" style JSON response for an exact path.

For example, any of these shapes would be useful:

Option A: `GET /some/path?json`

If the path points to a file or directory, return metadata for that exact path as a single JSON object instead of a directory listing.

Option B: dedicated query flag

Something like:

GET /some/path?stat
GET /some/path?meta
GET /some/path?json&stat

Option C: dedicated API endpoint

Something like:

GET /__dufs__/stat?path=/some/path

Example response

{
  "name": "file.txt",
  "path": "/dir/file.txt",
  "path_type": "File",
  "size": 12345,
  "mtime": 1712345678901
}

For directories, a similar response could be returned:

{
  "name": "dir",
  "path": "/dir",
  "path_type": "Dir",
  "size": 12,
  "mtime": 1712345678901
}

Why this would help

avoids listing large parent directories just to inspect one entry
easier to consume from scripts and API clients
simpler than using WebDAV PROPFIND
avoids XML parsing when JSON is preferred
makes dufs easier to use as a lightweight file metadata API

Thanks!

Originally created by @jgoedeke on GitHub (Apr 9, 2026). Original GitHub issue: https://github.com/sigoden/dufs/issues/682 ## Summary Please add a way to query metadata for a single file or directory path and get a JSON response, without having to list the parent directory and filter client-side. ## Current behavior Right now, the JSON API seems to be listing-oriented: - `?json` returns directory contents as a `paths` array - to get metadata for one specific path, I have to: 1. request the parent directory 2. parse the JSON response 3. filter for the entry I want This works, but it is awkward and inefficient, especially for large directories. ## Desired behavior Support a direct "stat" style JSON response for an exact path. For example, any of these shapes would be useful: ### Option A: `GET /some/path?json` If the path points to a file or directory, return metadata for that exact path as a single JSON object instead of a directory listing. ### Option B: dedicated query flag Something like: - `GET /some/path?stat` - `GET /some/path?meta` - `GET /some/path?json&stat` ### Option C: dedicated API endpoint Something like: - `GET /__dufs__/stat?path=/some/path` ## Example response ```json { "name": "file.txt", "path": "/dir/file.txt", "path_type": "File", "size": 12345, "mtime": 1712345678901 } ``` For directories, a similar response could be returned: ```json { "name": "dir", "path": "/dir", "path_type": "Dir", "size": 12, "mtime": 1712345678901 } ``` ## Why this would help - avoids listing large parent directories just to inspect one entry - easier to consume from scripts and API clients - simpler than using WebDAV `PROPFIND` - avoids XML parsing when JSON is preferred - makes `dufs` easier to use as a lightweight file metadata API Thanks!

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sigoden/dufs#1092

[GH-ISSUE #682] Add a JSON stat/metadata endpoint for a specific file or directory path #1092