Skip to content

Commit 546abfb

Browse files
joshtrichardsjoshtrichards
authored
docs(dev/WebDAV): missing properties and add'l clarifications
Signed-off-by: Josh <josh.t.richards@gmail.com>
1 parent 9dda358 commit 546abfb

1 file changed

Lines changed: 34 additions & 8 deletions

File tree

‎developer_manual/client_apis/WebDAV/basic.rst‎

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,11 @@ If a password is set for the share then a basic auth header must be sent with ``
3030

3131
.. note:: This endpoint for public shares is available since Nextcloud 29.
3232

33+
.. warning::
34+
For non-GET requests (e.g. PROPFIND, PUT) to ``/public.php/dav``, the request must include the header
35+
``X-Requested-With: XMLHttpRequest``, unless outgoing server-to-server sharing is enabled on the instance.
36+
Without this header, the server will reject the request with a ``401 Not Authenticated`` response.
37+
3338
Testing requests
3439
----------------
3540

@@ -241,8 +246,8 @@ Supported properties
241246
| <oc:permissions /> | | The permissions that the user has over the | | ``S``: Shared |
242247
| | | file or folder. The value is a string | | ``R``: Shareable |
243248
| | | containing letters for all available | | ``M``: Mounted |
244-
| | | permissions. | | ``G``: Readable |
245-
| | | | ``D``: Deletable |
249+
| | | permissions. On public shares, ``S`` and | | ``G``: Readable |
250+
| | | ``M`` are stripped from the returned value. | | ``D``: Deletable |
246251
| | | | ``N``: Renameable |
247252
| | | | ``V``: Moveable |
248253
| | | | ``W``: Writable (file) |
@@ -263,7 +268,7 @@ Supported properties
263268
| <nc:is-encrypted /> | Whether the folder is end-to-end encrypted. | | ``0`` for ``false`` |
264269
| | | | ``1`` for ``true`` |
265270
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
266-
| <nc:is-mount-root> | | This is a special property which is used to | ``true`` or ``false`` |
271+
| <nc:is-mount-root /> | | This is a special property which is used to | ``true`` or ``false`` |
267272
| | | determine if a node is a mount root or not, | |
268273
| | | e.g. a shared folder. If so, then the node | |
269274
| | | can only be unshared and not deleted. | |
@@ -323,7 +328,7 @@ Supported properties
323328
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
324329
| <nc:has-preview /> | Whether a preview of the file is available. | ``true`` or ``false`` |
325330
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
326-
| <nc:hidden> | | Defines if a file should be hidden | ``true`` or ``false`` |
331+
| <nc:hidden /> | | Defines if a file should be hidden | ``true`` or ``false`` |
327332
| | | Currently only used for live photos | |
328333
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
329334
| <oc:size /> | | Unlike ``getcontentlength``, this property | ``127815235`` |
@@ -391,6 +396,20 @@ Supported properties
391396
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
392397
| <nc:version-author /> | The author's id of a specified file version. | ``admin``, ``jane``, ``thisAuthorsID`` |
393398
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
399+
| <nc:is-federated /> | Whether the node originates from a | ``true`` or ``false`` |
400+
| | federated (server-to-server) share. | |
401+
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
402+
| <nc:metadata_etag /> | An etag representing the file's metadata state. | |
403+
| | Changes when metadata (not content) is updated. | |
404+
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
405+
| <nc:download-url-expiration />| Expiration date/time of a direct download URL, | |
406+
| | if one has been generated. | |
407+
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
408+
409+
.. note::
410+
Properties prefixed with ``nc:metadata-`` (e.g. ``nc:metadata-blurhash``) are dynamic, app-registered
411+
metadata properties. They are not listed individually here as they depend on which apps are enabled.
412+
You can request them via PROPFIND like any other property.
394413
395414
Listing folders (rfc4918_)
396415
--------------------------
@@ -444,6 +463,7 @@ Optionally it is possible to only include some files from the folder in the arch
444463
445464
As setting headers is not possible with HTML links it is also possible to provide this both options as query parameters.
446465
In this case the :code:`Accept` header value must be passed as the :code:`accept` query parameter.
466+
Both full MIME types (:code:`application/zip`, :code:`application/x-tar`) and shorthand values (:code:`zip`, :code:`tar`) are accepted.
447467
The optional files list can be provided as a JSON encoded array through the :code:`files` query parameter.
448468
449469
.. code::
@@ -568,20 +588,26 @@ You can set some special headers that Nextcloud will interpret.
568588
| | | if the mtime was accepted. | |
569589
+-----------------------+-----------------------------------------------------------------+------------------------------------------+
570590
| OC-Checksum | | A checksum that will be stored in the DB. | ``md5:04c36b75222cd9fd47f2607333029106`` |
571-
| | | The server will not do any sort of validation. | |
591+
| | | For regular ``PUT`` uploads, the server stores the value | |
592+
| | | without validation. During bulk uploads, the checksum | |
593+
| | | **is** validated against the uploaded content. | |
572594
| | | Currently used algorithms are ``MD5``, ``SHA1``, ``SHA256``, | |
573595
| | | ``SHA3-256``, ``Adler32``. | |
574596
+-----------------------+-----------------------------------------------------------------+------------------------------------------+
575-
| X-Hash | | Allow to request the file's hash from the server. | ``md5``, ``sha1``, or ``sha256`` |
576-
| | | The server will return the hash in a header named either: | |
577-
| | | ``X-Hash-MD5``, ``X-Hash-SHA1``, or ``X-Hash-SHA256``. | |
597+
| X-Hash | | On ``PUT`` requests, instructs the server to compute a hash | ``md5``, ``sha1``, ``sha256``, |
598+
| | | of the uploaded file content during the write. The server | or ``all`` |
599+
| | | returns the hash(es) in response headers named | |
600+
| | | ``X-Hash-MD5``, ``X-Hash-SHA1``, and/or ``X-Hash-SHA256``. | |
601+
| | | Setting the value to ``all`` computes all three hashes. | |
602+
| | | Beware of performance implications! | |
578603
+-----------------------+-----------------------------------------------------------------+------------------------------------------+
579604
| OC-Total-Length | | Contains the total size of the file during a chunk upload. | ``4052412`` |
580605
| | | This allow the server to abort faster if the remaining | |
581606
| | | user's quota is not enough. | |
582607
+-----------------------+-----------------------------------------------------------------+------------------------------------------+
583608
| X-NC-WebDAV-AutoMkcol | | When set to ``1``, instructs the server to automatically | |
584609
| | | create any missing parent directories when uploading a file. | |
610+
| | | Available since Nextcloud 32. | |
585611
+-----------------------+-----------------------------------------------------------------+------------------------------------------+
586612
| OC-Chunked | | Used for legacy chunk upload to differentiate a regular | Deprecated ⚠️ |
587613
| | | upload from a chunked upload. It allowed checking for quota | |

0 commit comments

Comments
 (0)