From 82c2cd0c858ce56b80d01405e8e4d1b255d2ac7f Mon Sep 17 00:00:00 2001 From: Ferdinand Thiessen Date: Sat, 28 Sep 2024 19:33:25 +0200 Subject: [PATCH] chore(developer): Add documentation about new WebDAV endpoint for downloading folders * Add WebDAV folder-download endpoint documenation * Add changelog entry for new endpoint * Add changelog entry for deprecated and removed legacy endpoints Signed-off-by: Ferdinand Thiessen --- .../app_upgrade_guide/upgrade_to_31.rst | 9 +++- developer_manual/client_apis/WebDAV/basic.rst | 53 ++++++++++++++++++- 2 files changed, 59 insertions(+), 3 deletions(-) diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst index 664107483dc..3b3a2a8c10b 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst @@ -68,6 +68,8 @@ Back-end changes Added APIs ^^^^^^^^^^ +- It is now possible to download folders as zip or tar archives using the WebDAV backend using :code:`GET` requests. + See the relevant :ref:`endpoint documentation`. - ``OCP\SetupCheck\CheckServerResponseTrait`` was added to ease implementing custom :ref:`setup checks` which need to check HTTP calls to the the server itself. Changed APIs @@ -79,12 +81,17 @@ Changed APIs Deprecated APIs ^^^^^^^^^^^^^^^ -- TBD +- The ``/s/{token}/download`` endpoint for downloading public shares is deprecated. + Instead use the Nextcloud provided :ref:`WebDAV endpoint`. Removed APIs ^^^^^^^^^^^^ - Legacy, non functional, ``OC_App::getForms`` was removed. +- The private and legacy ``OC_Files`` class was removed. + Instead use ``OCP\AppFramework\Http\StreamResponse`` or ``OCP\AppFramework\Http\ZipResponse``. +- The private and legacy Ajax endpoint for downloading file archives (``/apps/files/ajax/download.php``) was removed. + Instead use the Nextcloud provided :ref:`WebDAV endpoint`. - All ``OCP\ILogger`` logging methods, deprecated since Nextcloud 20, are removed. - The interface now only holds the Nextcloud internal logging level constants. For all logging ``Psr\Log\LoggerInterface`` should be used. diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 5097dc244db..2bfbfe8b0c5 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -10,11 +10,23 @@ for each operation, further information for each operation can be found in the c WebDAV basics ------------- -The base url for all WebDAV operations for a Nextcloud instance is :code:`/remote.php/dav`. +The base url for all (authenticated) WebDAV operations for a Nextcloud instance is :code:`/remote.php/dav`. All requests need to provide authentication information, either as a basic auth header or by passing a set of valid session cookies. -If your Nextcloud installation uses an external auth provider (such as an OIDC server) you may have to create an app password. To do that, go to your personal security settings and create one. It will provide a username and password which you can use within the Basic Auth header. +If your Nextcloud installation uses an external auth provider (such as an OIDC server) you may have to create an app password. +To do that, go to your personal security settings and create one. It will provide a username and password which you can use within the Basic Auth header. + +Public shares +^^^^^^^^^^^^^ + +The :code:`/remote.php/dav` endpoint only allows authenticated access to WebDAV resources, +for files shared using public link shares a different endpoint is provided which does not require authentication. + +The base URL for public link shares is :code:`/public.php/dav`, particularly for files: :code:`/public.php/dav/files/{share_token}`. +If a password is set for the share then a basic auth header must be sent with ``anonymous`` as the username and the share password as the password. + +.. note:: This endpoint for public shares is available since Nextcloud 29. Testing requests ---------------- @@ -343,12 +355,49 @@ You can request properties of a folder without also getting the folder contents Downloading files ----------------- +.. note:: The :code:`GET` method is not defined by the WebDAV standard, this is a Nextcloud provided WebDAV extension. +.. note:: For shared files this only works if the download permission was not denied by the sharer. + A file can be downloaded by sending a :code:`GET` request to the WebDAV url of the file. .. code:: GET remote.php/dav/files/user/path/to/file +.. _webdav-download-folders: + +Downloading folders +------------------- + +.. note:: The :code:`GET` method is not defined by the WebDAV standard, this is a Nextcloud provided WebDAV extension. +.. note:: For shared folders this only works if the download permission was not denied by the sharer. + +A folder can be downloaded as an archive by sending a :code:`GET` request to the WebDAV URL of the folder. +The :code:`Accept` header must be set and contain the MIME type for ZIP archives (:code:`application/zip`) or tarballs (:code:`application/x-tar`). + +.. code:: + + GET remote.php/dav/files/user/path/to/folder + Accept: application/zip + +Optionally it is possible to only include some files from the folder in the archive by providing the files using the custom :code:`X-NC-Files` header: + +.. code:: + + GET remote.php/dav/files/user/path/to/folder + Accept: application/zip + X-NC-Files: document.txt + X-NC-Files: image.png + +As setting headers is not possible with HTML links, and this endpoint is also used for downloading folders from the Nextcloud web interface, +it is also possible to provide this both options as query parameters. +In this case the :code:`Accept` header value must be passed as the :code:`accept` query parameter. +The optional files list can be provided as a JSON encoded array through the :code:`files` query parameter. + +.. code:: + + GET remote.php/dav/files/user/path/to/folder?accept=zip&files=%5B%22image.png%22%2C%22doucment.txt%22%5D + Uploading files ---------------