Skip to content

Commit 9dda358

Browse files
joshtrichardsjoshtrichards
authored
docs(dev): minor clarifications and typo fixes to WebDAV chapter
Signed-off-by: Josh <josh.t.richards@gmail.com>
1 parent 6328f1b commit 9dda358

1 file changed

Lines changed: 57 additions & 15 deletions

File tree

‎developer_manual/client_apis/WebDAV/basic.rst‎

Lines changed: 57 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,22 @@
11
.. _webdavindex:
22

3-
==========
4-
Basic APIs
5-
==========
3+
==============================
4+
Basic File & Folder Operations
5+
==============================
66

77
This document provides a quick overview of the WebDAV operations supported in Nextcloud, to keep things readable it won't go into many details
88
for each operation, further information for each operation can be found in the corresponding RFC where applicable.
99

1010
WebDAV basics
1111
-------------
1212

13-
The base url for all (authenticated) WebDAV operations for a Nextcloud instance is :code:`/remote.php/dav`.
13+
The base url for all (authenticated) WebDAV operations for a Nextcloud instance is :code:`/remote.php/dav`. For file operations, this usually
14+
means paths below :code:`/remote.php/dav/files/{user}/...`.
1415

1516
All requests need to provide authentication information, either as a basic auth header or by passing a set of valid session cookies.
1617

17-
If your Nextcloud installation uses an external auth provider (such as an OIDC server) you may have to create an app password.
18+
If your Nextcloud installation uses an external auth provider (such as an OIDC server) or enforces policies like 2FA, you may need to create an
19+
app password for WebDAV clients and scripts.
1820
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.
1921

2022
Public shares
@@ -82,12 +84,45 @@ Here is a JavaScript code sample to get you started:
8284
</d:propfind>`,
8385
})
8486
87+
Quick method/header cheat sheet
88+
-------------------------------
89+
90+
The table below summarizes common WebDAV methods used by Nextcloud and the most relevant headers.
91+
92+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
93+
| Method | Typical endpoint | Important request headers | Notes |
94+
+============+===========================================+=============================================+==============================================================+
95+
| PROPFIND | ``/remote.php/dav/files/{user}/path`` | ``Depth: 0`` (properties of node only) | Without ``Depth: 0``, folder listings include child entries.|
96+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
97+
| REPORT | ``/remote.php/dav/files/{user}/path`` | (none required) | Used for filtered queries such as favorites. |
98+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
99+
| GET (file) | ``/remote.php/dav/files/{user}/file`` | (none required) | Downloads file content. |
100+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
101+
| GET (dir) | ``/remote.php/dav/files/{user}/folder`` | ``Accept: application/zip`` or | Nextcloud extension for folder archive download. |
102+
| | | ``Accept: application/x-tar`` | |
103+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
104+
| PUT | ``/remote.php/dav/files/{user}/file`` | Optional: ``X-OC-MTime``, ``X-OC-CTime``, | Uploads/overwrites file content. |
105+
| | | ``OC-Checksum``, ``OC-Total-Length``, | |
106+
| | | ``X-NC-WebDAV-AutoMkcol`` | |
107+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
108+
| MKCOL | ``/remote.php/dav/files/{user}/folder`` | (none required) | Creates a folder. |
109+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
110+
| DELETE | ``/remote.php/dav/files/{user}/path`` | (none required) | Folder deletes are recursive. |
111+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
112+
| MOVE | ``/remote.php/dav/files/{user}/path`` | ``Destination: <full URL>`` | Optional: ``Overwrite: T`` (default) or ``Overwrite: F``. |
113+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
114+
| COPY | ``/remote.php/dav/files/{user}/path`` | ``Destination: <full URL>`` | Optional: ``Overwrite: T`` (default) or ``Overwrite: F``. |
115+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
116+
| PROPPATCH | ``/remote.php/dav/files/{user}/path`` | (none required) | Sets properties such as ``oc:favorite``. |
117+
+------------+-------------------------------------------+---------------------------------------------+--------------------------------------------------------------+
118+
85119
Requesting properties
86120
---------------------
87121
88122
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.
89123
90124
You can request additional properties by sending a request body with the :code:`PROPFIND` request that lists all requested properties.
125+
If a property is not supported for a resource, the server will report it as not found in the multi-status response for that property.
91126
92127
.. code-block:: xml
93128
@@ -135,17 +170,22 @@ And here is how it should look in your DAV request:
135170
.. code-block:: xml
136171
137172
<?xml version="1.0"?>
138-
<d:propfind
139-
xmlns:d="DAV:"
140-
xmlns:oc="http://owncloud.org/ns"
141-
xmlns:nc="http://nextcloud.org/ns"
142-
xmlns:ocs="http://open-collaboration-services.org/ns">
143-
xmlns:ocm="http://open-cloud-mesh.org/ns">
173+
<d:propfind
174+
xmlns:d="DAV:"
175+
xmlns:oc="http://owncloud.org/ns"
176+
xmlns:nc="http://nextcloud.org/ns"
177+
xmlns:ocs="http://open-collaboration-services.org/ns"
178+
xmlns:ocm="http://open-cloud-mesh.org/ns">
144179
...
180+
</d:propfind>
145181
146182
Supported properties
147183
^^^^^^^^^^^^^^^^^^^^
148184
185+
.. note::
186+
Properties in the ``d:`` namespace are standard WebDAV properties (RFC 4918).
187+
Most properties in ``oc:``, ``nc:``, ``ocs:``, and ``ocm:`` are Nextcloud-specific extensions.
188+
149189
+-------------------------------+-------------------------------------------------+--------------------------------------------------------------------------------------+
150190
| Property | Description | Example |
151191
+===============================+=================================================+======================================================================================+
@@ -410,6 +450,8 @@ The optional files list can be provided as a JSON encoded array through the :cod
410450
411451
GET remote.php/dav/files/user/path/to/folder?accept=zip&files=["image.png","document.txt"]
412452
453+
When using query parameters, ensure values are URL-encoded. In particular, :code:`files` must be a URL-encoded JSON array.
454+
413455
Uploading files
414456
---------------
415457
@@ -451,7 +493,7 @@ A file or folder can be moved by sending a :code:`MOVE` request to the file or f
451493
MOVE remote.php/dav/files/user/path/to/file
452494
Destination: https://cloud.example/remote.php/dav/files/user/new/location
453495
454-
The overwrite behavior of the move can be controlled by setting the :code:`Overwrite` head to :code:`T` or :code:`F` to enable or disable overwriting respectively.
496+
The overwrite behavior of the move can be controlled by setting the :code:`Overwrite` header to :code:`T` or :code:`F` to enable or disable overwriting respectively.
455497
456498
Copying files and folders (rfc4918_)
457499
------------------------------------
@@ -463,12 +505,12 @@ A file or folder can be copied by sending a :code:`COPY` request to the file or
463505
COPY remote.php/dav/files/user/path/to/file
464506
Destination: https://cloud.example/remote.php/dav/files/user/new/location
465507
466-
The overwrite behavior of the copy can be controlled by setting the :code:`Overwrite` head to :code:`T` or :code:`F` to enable or disable overwriting respectively.
508+
The overwrite behavior of the copy can be controlled by setting the :code:`Overwrite` header to :code:`T` or :code:`F` to enable or disable overwriting respectively.
467509
468510
Settings favorites
469511
------------------
470512
471-
A file or folder can be marked as favorite by sending a :code:`PROPPATCH` request to the file or folder and setting the :code:`oc-favorite` property
513+
A file or folder can be marked as favorite by sending a :code:`PROPPATCH` request to the file or folder and setting the :code:`oc:favorite` property.
472514
473515
.. code-block:: xml
474516
@@ -487,7 +529,7 @@ Setting the :code:`oc:favorite` property to ``1`` marks a file as favorite, sett
487529
Listing favorites
488530
-----------------
489531
490-
Favorites for a user can be retrieved by sending a :code:`REPORT` request and specifying :code:`oc:favorite` as a filter
532+
Favorites for a user can be retrieved by sending a :code:`REPORT` request and specifying :code:`oc:favorite` as a filter.
491533
492534
.. code-block:: xml
493535

0 commit comments

Comments
 (0)