Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Explain more clearly how to use rest/db/file #817

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Explain more clearly how to use rest/db/file #817

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ba778fd
Explain more clearly how to use rest/db/file
timabell Aug 20, 2023
f395522
Update rest/db-file-get.rst
timabell Aug 20, 2023
09acbbd
Update rest/db-file-get.rst
timabell Aug 20, 2023
2a2a472
Update rest/db-file-get.rst
timabell Aug 20, 2023
9e7f80d
Update rest/db-file-get.rst
timabell Aug 20, 2023
bad8f05
Update rest/db-file-get.rst
timabell Aug 20, 2023
8e0308f
Fix typo in patch
timabell Aug 20, 2023
89ee8d1
Avoid confusing use of "full path" for file path
timabell Aug 20, 2023
383dfc2
Re-wrap text flow and add code syntax blocks.
acolomb Aug 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 33 additions & 9 deletions rest/db-file-get.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,31 @@
GET /rest/db/file
=================

Returns most data available about a given file, including version and
availability. Takes ``folder`` and ``file`` parameters. ``local`` and
``global`` refer to the current file on disk and the globally newest file,
respectively.
Returns data about a given file, including version and availability.

.. code-block::
Request
-------

The call requires parameters for `folder` and `file` in the query string:

- `folder` is the folder ID which you can find in the Syncthing Web GUI,
e.g. `5camp-slpa8`.

- `file` is the relative path of the file starting from the folder root to the
file you are interested in. The path and filename must be correctly
URL-encoded.

Example Request
^^^^^^^^^^^^^^^

.. code-block:: bash

curl --silent --get --header "X-API-KEY: YOUR_API_TOKEN" "http://localhost:8384/rest/db/file?folder=YOUR_FOLDER_ID" --data-urlencode "file=path/to/file.pdf"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are already numerous examples involving curl in the docs. I'd find it convenient to adopt the same CLI options used there, e.g. -H instead of --header and omit the --get.


Response
--------

.. code-block:: json

{
"availability": [
Expand All @@ -19,7 +38,10 @@ respectively.
"local": { /* a file entry */ }
}

A file entry looks like this::
``local`` and ``global`` refer to the current file on the local device and the
globally newest file, respectively. A file entry looks like this:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a factual error here. The mtime attribute is not part of the respective file entry, but top-level next to availability. When that is fixed, the outer object wrapping can go away in this code sample.


.. code-block:: json

{
{
Expand Down Expand Up @@ -53,9 +75,11 @@ A file entry looks like this::
}

Platform specific data may be ownership, extended attributes, etc. and is
divided into entries per operating system / platform. An example platform
entry containing ownership information for Unix systems and an extended
attribute for macOS ("darwin") looks as follows::
divided into entries per operating system / platform. An example platform entry
containing ownership information for Unix systems and an extended attribute for
macOS ("darwin") looks as follows:

.. code-block:: json

{
"darwin": {
Expand Down
Loading