diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 57d01eda2..8a664bf65 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -102,158 +102,81 @@ You can request additional properties by sending a request body with the :code:` The following properties are supported: ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| Property | Description | Example | ++===============================+===================================================+=============================================+ +| | The latest modification time. | ``"Wed, 20 Jul 2022 05:12:23 GMT"`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The file's etag. | ``""6436d084d4805""`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The mime type of the file. | ``"image/jpeg"`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | Specifies the nature of the resource. | ```` for a folder | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The size if it is a file. | ``3030237`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | The fileid namespaced by the instance id. | | +| | | Globally unique. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The unique id for the file within the instance. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The permissions that the user has over the file. | ``true`` or ``false`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The type of mount. | | ``''`` = local | +| | | | ``'shared'`` = received share | +| | | | ``'external'`` = external storage | +| | | | ``'external-session'`` = external storage | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` | +| | | | ``1`` for ``true`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The favorite state. | | ``0`` for not favourited | +| | | | ``1`` for favourited | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The DAV endpoint to fetch the comments. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The number of comments. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The number of unread comments. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The user id of the owner of a shared file. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The display name of the owner of a shared file. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The list of type share. | | ``0`` = User | +| | | | ``1`` = Group | +| | | | ``3`` = Public link | +| | | | ``4`` = Email | +| | | | ``6`` = Federated cloud share | +| | | | ``7`` = Circle | +| | | | ``10`` = Talk conversation | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | The permissions that the user has over the share. | | ``4`` = Create | +| | | | ``1`` = Read | +| | | | ``2`` = Update | +| | | | ``8`` = Delete | +| | | | ``16`` = Share | +| | | | ``31`` = All | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | Whether a preview of the file is available | ``true`` or ``false`` | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | Unlike :code:`getcontentlength`, | | +| | | this property also works | | +| | | for folders, reporting the size | | +| | | of everything in the folder. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | This property is provided by the text app. | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | The number of folders directly contained | | +| | | in the folder (not recursively). | | ++-------------------------------+---------------------------------------------------+---------------------------------------------+ +| | | 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_) @@ -383,17 +306,41 @@ 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. ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| Header | Description | Example | ++=================+=================================================================+==================================+ +| X-OC-MTime | | Allow to specify a mtime. | ``1675789581`` | +| | | The response will contain the header ``X-OC-MTime: accepted`` | | +| | | if the mtime was accepted. | | ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| X-OC-CTime | | Allow to specify a creation time. | ``1675789581`` | +| | | The response will contain the header ``X-OC-CTime: accepted`` | | +| | | if the mtime was accepted. | | ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| OC-Checksum | Allow to specify a checksum. | | ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| X-Hash | | Allow to request the file's hash from the server. | ``md5``, ``sha1``, or ``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. | ``true`` | ++-----------------+-----------------------------------------------------------------+----------------------------------+ +| OC-Total-Length | | Contains the total size of the file during a chunk upload. | ``4052412`` | +| | | This allow the server to abort faster if the remaining | | +| | | user's quota is not enough. | | ++-----------------+-----------------------------------------------------------------+----------------------------------+ Response Headers ---------------- -Nextcloud will answer with +Nextcloud will sometime answer with the following headers: -- ``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"`` ++-----------+------------------------------------------------+-----------------------------------------+ +| Header | Description | Example | ++===========+================================================+=========================================+ +| OC-Etag | | On creation, move and copy, | ``"50ef2eba7b74aa84feff013efee2a5ef"`` | +| | | the response contain the etag of the file. | | ++-----------+------------------------------------------------+-----------------------------------------+ +| OC-FileId | | On creation, move and copy, | | Format: ````. | +| | | the response contain the fileid of the file. | | Example: ``00000259oczn5x60nrdu`` | ++-----------+------------------------------------------------+-----------------------------------------+