From ba778fdc9f2e9acc8cc298bda92f1660a229f6da Mon Sep 17 00:00:00 2001 From: Tim Abell Date: Sun, 20 Aug 2023 15:29:16 +0100 Subject: [PATCH 1/9] Explain more clearly how to use rest/db/file This adds an example curl call and explains the parameters more clearly. It's not immediately obvious how to use this endpoint from the existing docs. Hopefully this will help others figure it out. Reading the forums I don't think I was the only person confused by this page. --- rest/db-file-get.rst | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/rest/db-file-get.rst b/rest/db-file-get.rst index aa6d9a2cd..32a16ddf0 100644 --- a/rest/db-file-get.rst +++ b/rest/db-file-get.rst @@ -1,10 +1,27 @@ 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. + +Request +------- + +The call requires parameters for `folder` and `file` in the querystring: + +- `folder` is the folder code which you can find in the synthing UI, e.g. `5camp-slpa8` + +- `file` is the full path to the file you are interested in. The path and filename must be correctly url-encoded. + + +Example Request +^^^^^^^^^^^^^^^ + + curl --silent --get --header "X-API-KEY: YOUR_API_TOKEN" "http://localhost:8080/rest/db/file?folder=YOUR_FOLDER_ID" --data-urlencode "file=path/to/file.pdf" + +Response +-------- + .. code-block:: @@ -19,6 +36,8 @@ respectively. "local": { /* a file entry */ } } +``local`` and ``global`` refer to the current file on disk and the globally newest file, respectively. + A file entry looks like this:: { From f3955227906b89d59786a7316cf692fe28e1172a Mon Sep 17 00:00:00 2001 From: Tim Abell Date: Sun, 20 Aug 2023 16:18:41 +0100 Subject: [PATCH 2/9] Update rest/db-file-get.rst Co-authored-by: tomasz1986 --- rest/db-file-get.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest/db-file-get.rst b/rest/db-file-get.rst index 32a16ddf0..8afc0277d 100644 --- a/rest/db-file-get.rst +++ b/rest/db-file-get.rst @@ -7,7 +7,7 @@ availability. Request ------- -The call requires parameters for `folder` and `file` in the querystring: +The call requires parameters for `folder` and `file` in the query string: - `folder` is the folder code which you can find in the synthing UI, e.g. `5camp-slpa8` From 09acbbdab3d879373c494c7adb8a6e5731837ca3 Mon Sep 17 00:00:00 2001 From: Tim Abell Date: Sun, 20 Aug 2023 16:18:52 +0100 Subject: [PATCH 3/9] Update rest/db-file-get.rst Co-authored-by: tomasz1986 --- rest/db-file-get.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest/db-file-get.rst b/rest/db-file-get.rst index 8afc0277d..ad1c9bed6 100644 --- a/rest/db-file-get.rst +++ b/rest/db-file-get.rst @@ -9,7 +9,7 @@ Request The call requires parameters for `folder` and `file` in the query string: -- `folder` is the folder code which you can find in the synthing UI, e.g. `5camp-slpa8` +- `folder` is the folder ID which you can find in the Synthing Web GUI, e.g. `5camp-slpa8` - `file` is the full path to the file you are interested in. The path and filename must be correctly url-encoded. From 2a2a4727d5d7af992cb02b7ff91cbbfb11e9a2c2 Mon Sep 17 00:00:00 2001 From: Tim Abell Date: Sun, 20 Aug 2023 16:19:12 +0100 Subject: [PATCH 4/9] Update rest/db-file-get.rst Co-authored-by: tomasz1986 --- rest/db-file-get.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest/db-file-get.rst b/rest/db-file-get.rst index ad1c9bed6..bf36ed044 100644 --- a/rest/db-file-get.rst +++ b/rest/db-file-get.rst @@ -11,7 +11,7 @@ The call requires parameters for `folder` and `file` in the query string: - `folder` is the folder ID which you can find in the Synthing Web GUI, e.g. `5camp-slpa8` -- `file` is the full path to the file you are interested in. The path and filename must be correctly url-encoded. +- `file` is the full path starting from the folder root to the file you are interested in. The path and filename must be correctly URL-encoded. Example Request From 9e7f80db0798cb2e315cd88f096f42e7459f5e8f Mon Sep 17 00:00:00 2001 From: Tim Abell Date: Sun, 20 Aug 2023 16:19:21 +0100 Subject: [PATCH 5/9] Update rest/db-file-get.rst Co-authored-by: tomasz1986 --- rest/db-file-get.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest/db-file-get.rst b/rest/db-file-get.rst index bf36ed044..2a80899c2 100644 --- a/rest/db-file-get.rst +++ b/rest/db-file-get.rst @@ -17,7 +17,7 @@ The call requires parameters for `folder` and `file` in the query string: Example Request ^^^^^^^^^^^^^^^ - curl --silent --get --header "X-API-KEY: YOUR_API_TOKEN" "http://localhost:8080/rest/db/file?folder=YOUR_FOLDER_ID" --data-urlencode "file=path/to/file.pdf" + 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" Response -------- From bad8f05a3bedaa7e5c39f4e7961d9c2db6eaa0a6 Mon Sep 17 00:00:00 2001 From: Tim Abell Date: Sun, 20 Aug 2023 16:19:30 +0100 Subject: [PATCH 6/9] Update rest/db-file-get.rst Co-authored-by: tomasz1986 --- rest/db-file-get.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest/db-file-get.rst b/rest/db-file-get.rst index 2a80899c2..4dc708b78 100644 --- a/rest/db-file-get.rst +++ b/rest/db-file-get.rst @@ -36,7 +36,7 @@ Response "local": { /* a file entry */ } } -``local`` and ``global`` refer to the current file on disk and the globally newest file, respectively. +``local`` and ``global`` refer to the current file on the local device and the globally newest file, respectively. A file entry looks like this:: From 8e0308fe1d593b98a8699e2b15762bbac322ce6d Mon Sep 17 00:00:00 2001 From: Tim Abell Date: Sun, 20 Aug 2023 16:20:49 +0100 Subject: [PATCH 7/9] Fix typo in patch --- rest/db-file-get.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest/db-file-get.rst b/rest/db-file-get.rst index 4dc708b78..ee4e14370 100644 --- a/rest/db-file-get.rst +++ b/rest/db-file-get.rst @@ -9,7 +9,7 @@ Request The call requires parameters for `folder` and `file` in the query string: -- `folder` is the folder ID which you can find in the Synthing Web GUI, e.g. `5camp-slpa8` +- `folder` is the folder ID which you can find in the Syncthing Web GUI, e.g. `5camp-slpa8` - `file` is the full path starting from the folder root to the file you are interested in. The path and filename must be correctly URL-encoded. From 89ee8d1ab11b5bb1fe9fcf5b3daac1211d9af55e Mon Sep 17 00:00:00 2001 From: Tim Abell Date: Sun, 20 Aug 2023 16:22:19 +0100 Subject: [PATCH 8/9] Avoid confusing use of "full path" for file path PR feedback --- rest/db-file-get.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest/db-file-get.rst b/rest/db-file-get.rst index ee4e14370..a2466ca6d 100644 --- a/rest/db-file-get.rst +++ b/rest/db-file-get.rst @@ -11,7 +11,7 @@ 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 full path starting from the folder root to the file you are interested in. The path and filename must be correctly URL-encoded. +- `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 From 383dfc2d4eb119f0b92ffcf6f152aacdf092fb8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Colomb?= Date: Mon, 21 Aug 2023 07:08:04 +0200 Subject: [PATCH 9/9] Re-wrap text flow and add code syntax blocks. --- rest/db-file-get.rst | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/rest/db-file-get.rst b/rest/db-file-get.rst index a2466ca6d..2f70935c8 100644 --- a/rest/db-file-get.rst +++ b/rest/db-file-get.rst @@ -1,29 +1,31 @@ GET /rest/db/file ================= -Returns data about a given file, including version and -availability. +Returns data about a given file, including version and availability. 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. +- `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 ^^^^^^^^^^^^^^^ - 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" +.. 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" Response -------- - -.. code-block:: +.. code-block:: json { "availability": [ @@ -36,9 +38,10 @@ Response "local": { /* a file entry */ } } -``local`` and ``global`` refer to the current file on the local device and the globally newest file, respectively. +``local`` and ``global`` refer to the current file on the local device and the +globally newest file, respectively. A file entry looks like this: -A file entry looks like this:: +.. code-block:: json { { @@ -72,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": {