From 43ca2eb7bc0eeef74ac497a8477a59fbcd63e31b Mon Sep 17 00:00:00 2001 From: Louis Chemineau Date: Thu, 13 Apr 2023 14:30:30 +0200 Subject: [PATCH] Improve webdav documentation Signed-off-by: Louis Chemineau --- developer_manual/client_apis/WebDAV/basic.rst | 282 +++++++++++++++--- 1 file changed, 235 insertions(+), 47 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 26a668d4a..57d01eda2 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -5,51 +5,73 @@ Basic APIs ========== This document provides a quick overview of the WebDAV operations supported in Nextcloud, to keep things readable it won't go into many details -for each operation, further information for each operation can be found in the corresponding rfc where applicable +for each operation, further information for each operation can be found in the corresponding RFC where applicable. WebDAV basics ------------- The base url for all 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. +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 browse to your user Settings > Security 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. -Testing requests with curl --------------------------- +Testing requests +---------------- -All WebDAV requests can be easily tested out using :code:`curl` by specifying the request method (:code:`GET`, :code:`PROPFIND`, :code:`PUT`, etc) and setting a request body where needed. +With curl +^^^^^^^^^ -For example: you can perform a :code:`PROPFIND` request to find files in a folder using +All WebDAV requests can be easily tested out using :code:`curl` by specifying the request method (:code:`GET`, :code:`PROPFIND`, :code:`PUT`, ...) and providing a request body where needed. +For example: you can perform a :code:`PROPFIND` request to find files in a folder using: .. code-block:: bash - curl -u username:password 'https://cloud.example.com/remote.php/dav/files/username/folder' -X PROPFIND --data ' - - - - - - - - - - ' + curl 'https://cloud.example.com/remote.php/dav/files/username/folder' \ + --user username:password \ + --request PROPFIND \ + --data ' + + + + + + + + + + ' +Making requests in JavaScript +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Listing folders (rfc4918_) --------------------------- +Here is a JavaScript code sample to get you started: -The contents of a folder can be listed by sending a :code:`PROPFIND` request to the folder. +.. code-block:: javascript -.. code:: + import { createClient } from 'webdav' + import { generateRemoteUrl } from '@nextcloud/router' + import { getCurrentUser } from '@nextcloud/auth' - PROPFIND remote.php/dav/files/user/path/to/folder + const client = createClient(generateRemoteUrl('dav')) + const response = await client.getDirectoryContents(`/files/${getCurrentUser()?.uid}/folder`, { + details: true, + data: ` + + + + + + + + + + `, + }) Requesting properties -^^^^^^^^^^^^^^^^^^^^^ +--------------------- By default, a :code:`PROPFIND` request will only return a small number of properties for each file: last modified date, file size, whether it's a folder, etag and mime type. @@ -80,26 +102,168 @@ You can request additional properties by sending a request body with the :code:` The following properties are supported: -- :code:`{DAV:}getlastmodified` -- :code:`{DAV:}getetag` -- :code:`{DAV:}getcontenttype` -- :code:`{DAV:}resourcetype` -- :code:`{DAV:}getcontentlength` -- :code:`{http://owncloud.org/ns}id` The fileid namespaced by the instance id, globally unique -- :code:`{http://owncloud.org/ns}fileid` The unique id for the file within the instance -- :code:`{http://owncloud.org/ns}favorite` -- :code:`{http://owncloud.org/ns}comments-href` -- :code:`{http://owncloud.org/ns}comments-count` -- :code:`{http://owncloud.org/ns}comments-unread` -- :code:`{http://owncloud.org/ns}owner-id` The user id of the owner of a shared file -- :code:`{http://owncloud.org/ns}owner-display-name` The display name of the owner of a shared file -- :code:`{http://owncloud.org/ns}share-types` -- :code:`{http://owncloud.org/ns}checksums` -- :code:`{http://nextcloud.org/ns}has-preview` -- :code:`{http://owncloud.org/ns}size` Unlike :code:`getcontentlength`, this property also works for folders reporting the size of everything in the folder. -- :code:`{http://nextcloud.org/ns}rich-workspace` this property is provided by the text app -- :code:`{http://nextcloud.org/ns}contained-folder-count` The number of folders directly contained in the folder (not recursively) -- :code:`{http://nextcloud.org/ns}contained-file-count` The number of files directly contained in the folder (not recursively) + +getlastmodified +^^^^^^^^^^^^^^^ +- Id: ``{DAV:}getlastmodified`` +- Property: ```` +- Description: The latest modification time. +- Example: ``"Wed, 20 Jul 2022 05:12:23 GMT"`` + +getetag +^^^^^^^ +- Id: ``{DAV:}getetag`` +- Property: ```` +- Description: The file's etag. +- Example: ``""6436d084d4805""`` + +getcontenttype +^^^^^^^^^^^^^^ +- Id: ``{DAV:}getcontenttype`` +- Property: ```` +- Description: The mime type of the file. +- Example: ``"image/jpeg"`` + +resourcetype +^^^^^^^^^^^^ +- Id: ``{DAV:}resourcetype`` +- Property: ```` +- Description: Specifies the nature of the resource. +- Example: ```` for a folder + +getcontentlength +^^^^^^^^^^^^^^^^ +- Id: ``{DAV:}getcontentlength`` +- Property: ```` +- Description: The size if it is a file. +- Example: ``3030237`` + +id +^^ +- Id: ``{http://owncloud.org/ns}id`` +- Property: ```` +- Description: The fileid namespaced by the instance id, globally unique + +fileid +^^^^^^ +- Id: ``{http://owncloud.org/ns}fileid`` +- Property: ```` +- Description: The unique id for the file within the instance + +permissions +^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}permissions`` +- Property: ```` +- Description: The permissions that the user has over the file. ``true`` or ``false`` + +mount-type +^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}mount-type`` +- Property: ```` +- Description: The type of mount. +- Example: ``''`` = local; ``'shared'`` = received share; ``'external'`` or ``'external-session'`` = external storage + +is-encrypted +^^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}is-encrypted`` +- Property: ```` +- Description: Whether the file is end-to-end encrypted + +favorite +^^^^^^^^ +- Id: ``{http://owncloud.org/ns}favorite`` +- Property: ```` +- Description: The favorite state. +- Example: ``0`` for not favourited, ``1`` for favourited + +comments-href +^^^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}comments-href`` +- Property: ```` +- Description: The DAV endpoint to fetch teh comments + +comments-count +^^^^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}comments-count`` +- Property: ```` +- Description: The number of comments + +comments-unread +^^^^^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}comments-unread`` +- Property: ```` +- Description: The number of unread comments + +owner-id +^^^^^^^^ +- Id: ``{http://owncloud.org/ns}owner-id`` +- Property: ```` +- Description: The user id of the owner of a shared file + +owner-display-name +^^^^^^^^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}owner-display-name`` +- Property: ```` +- Description: The display name of the owner of a shared file + +share-types +^^^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}share-types`` +- Property: ```` +- Description: The list of type share. +- Example: ``0`` = user; ``1`` = group; ``3`` = public link; ``4`` = email; ``6`` = federated cloud share; ``7`` = circle; ``10`` = Talk conversation + +share-permissions +^^^^^^^^^^^^^^^^^ +- Id: ``{http://open-collaboration-services.org/ns}share-permissions`` +- Property: ``{http://open-collaboration-services.org/ns}share-permissions`` +- Description: The permissions that the user has over the share. +- Example: Create = ``4``; Read = ``1``; Update = ``2``; Delete = ``8``; Share = ``16``; All = ``31``; + +checksums +^^^^^^^^^ +- Id: ``{http://owncloud.org/ns}checksums`` +- Property: ```` +- Description: +has-preview +^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}has-preview`` +- Property: ```` +- Description: Whether a preview of the file is available + +size +^^^^ +- Id: ``{http://owncloud.org/ns}size`` +- Property: ```` +- Description: Unlike :code:`getcontentlength`, this property also works for folders reporting the size of everything in the folder + +rich-workspace +^^^^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}rich-workspace`` +- Property: ```` +- Description: This property is provided by the text app + +contained-folder-count +^^^^^^^^^^^^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}contained-folder-count`` +- Property: ```` +- Description: The number of folders directly contained in the folder (not recursively) + +contained-file-count +^^^^^^^^^^^^^^^^^^^^ +- Id: ``{http://nextcloud.org/ns}contained-file-count`` +- Property: ```` +- Description: The number of files directly contained in the folder (not recursively) + + +Listing folders (rfc4918_) +-------------------------- + +The contents of a folder can be listed by sending a :code:`PROPFIND` request to the folder. + +.. code:: + + PROPFIND remote.php/dav/files/user/path/to/folder Getting properties for just the folder ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -118,7 +282,7 @@ A file can be downloaded by sending a :code:`GET` request to the WebDAV url of t Uploading files --------------- -A file can be uploading by sending a :code:`PUT` request to the file and sending the raw file contents as the request body. +A file can be uploaded by sending a :code:`PUT` request to the file and sending the raw file contents as the request body. .. code:: @@ -144,7 +308,7 @@ A file or folder can be deleted by sending a :code:`DELETE` request to the file DELETE remote.php/dav/files/user/path/to/file -When deleting a folder, it's contents will be deleted recursively. +When deleting a folder, its contents will be deleted recursively. Moving files and folders (rfc4918_) ----------------------------------- @@ -187,7 +351,7 @@ A file or folder can be marked as favorite by sending a :code:`PROPPATCH` reques -Setting the :code:`oc:favorite` property to 1 marks a file as favorite, setting it to 0 un-marks it as favorite. +Setting the :code:`oc:favorite` property to ``1`` marks a file as favorite, setting it to ``0`` un-marks it as favorite. Listing favorites ----------------- @@ -209,3 +373,27 @@ File properties can be requested by adding a :code:`` element to the re When listing favorites, the request will find all favorites in the folder recursively, all favorites for a user can be found by sending the request to :code:`remote.php/dav/files/user` .. _rfc4918: https://tools.ietf.org/html/rfc4918 + + +Special Headers +--------------- + +Request Headers +^^^^^^^^^^^^^^^ + +You can set some special headers that Nextcloud will interpret. + +- ``X-OC-MTIME``: allow to specify a mtime. The response will contain the header ``X-OC-MTime: accepted`` if the mtime was accepted. +- ``X-OC-CTIME``: allow to specify a creation time. The response will contain the header ``X-OC-CTime: accepted`` if the ctime was accepted. +- ``OC-CHECKSUM``: allow to specify a checksum. +- ``X-HASH``: allow to request the file's hash from the server. Possible values are ``md5``, ``sha1``, and ``sha256``. The server will return the hash in a header named either ``X-Hash-MD5``, ``X-Hash-SHA1``, or ``X-Hash-SHA256``. +- ``OC-CHUNKED``: specify that the sent data is part of a chunk upload. +- ``OC-Total-Length``: contains the total size of the file during a chunk upload. This allow the server to abort faster if the remaining user's quota is not enough. + +Response Headers +---------------- + +Nextcloud will answer with + +- ``OC-Etag``: On creation, move and copy, the response contain the etag of the file. +- ``OC-FileId``: On creation, move and copy, the response contain the fileid of the file. Format: ````. Example: ``"00000259oczn5x60nrdu"``