From 1a98f9c5055f52dc6af1b6247e581ea4e28b9d77 Mon Sep 17 00:00:00 2001 From: Roeland Jago Douma Date: Thu, 3 Jan 2019 20:41:01 +0100 Subject: [PATCH 1/3] Properly nest the client APIs Signed-off-by: Roeland Jago Douma --- developer_manual/client_apis/OCS/index.rst | 15 +- developer_manual/client_apis/WebDAV/basic.rst | 204 +++++++++++++++++ developer_manual/client_apis/WebDAV/index.rst | 210 +----------------- developer_manual/client_apis/index.rst | 34 --- 4 files changed, 223 insertions(+), 240 deletions(-) create mode 100644 developer_manual/client_apis/WebDAV/basic.rst diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst index 6fb6910b5..94afccd64 100644 --- a/developer_manual/client_apis/OCS/index.rst +++ b/developer_manual/client_apis/OCS/index.rst @@ -72,9 +72,9 @@ Clients can obtain capabilities provided by the Nextcloud server and its apps vi .. code:: GET /ocs/v1.php/cloud/capabilities - - - + + + .. code:: xml @@ -102,8 +102,8 @@ Clients can obtain capabilities provided by the Nextcloud server and its apps vi - - + + Theming capabilities -------------------- @@ -123,3 +123,8 @@ Values of the theming app are exposed though the capabilities API, allowing clie The background value can either be an URL to the background image or a hex color value. +Notifications +------------- + +There is also the `Notifications API `_ +As well as documentation on how to `Register a device for push notifications `_ diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst new file mode 100644 index 000000000..1e22e1f0c --- /dev/null +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -0,0 +1,204 @@ +.. _webdavindex: + +================== +WebDAV client 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 + +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. + +Testing requests with curl +-------------------------- + +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. + +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 ' + + + + + + + + + + ' + + +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 + +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. + +You can request additional properties by sending a request body with the :code:`PROPFIND` request that lists all requested properties. + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + +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. + +Getting properties for just the folder +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can request properties of a folder without also getting the folder contents by adding a :code:`Depth: 0` header to the request. + +Downloading files +----------------- + +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 + +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. + +.. code:: + + PUT remote.php/dav/files/user/path/to/file + +Any existing file will be overwritten by the request. + +Creating folders (rfc4918_) +--------------------------- + +A folder can be created by sending a :code:`MKCOL` request to the folder. + +.. code:: + + MKCOL remote.php/dav/files/user/path/to/new/folder + +Deleting files and folders (rfc4918_) +------------------------------------- + +A file or folder can be created by sending a :code:`DELETE` request to the file or folder. + +.. code:: + + DELETE remote.php/dav/files/user/path/to/file + +When deleting a folder, it's contents will be deleted recursively. + +Moving files and folders (rfc4918_) +----------------------------------- + +A file or folder can be moved by sending a :code:`MOVE` request to the file or folder and specifying the destination in the :code:`Destination` header as full url. + +.. code:: + + MOVE remote.php/dav/files/user/path/to/file + Destination: https://cloud.example/remote.php/dav/files/user/new/location + +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. + +Copying files and folders (rfc4918_) +------------------------------------ + +A file or folder can be copied by sending a :code:`COPY` request to the file or folder and specifying the destination in the :code:`Destination` header as full url. + +.. code:: + + COPY remote.php/dav/files/user/path/to/file + Destination: https://cloud.example/remote.php/dav/files/user/new/location + +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. + +Settings favorites +------------------ + +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 + +.. code-block:: xml + + PROPPATCH remote.php/dav/files/user/path/to/file + + + + + 1 + + + + +Setting the :code:`oc:favorite` property to 1 marks a file as favorite, setting it to 0 un-marks it as favorite. + +Listing favorites +----------------- + +Favorites for a user can be retrieved by sending a :code:`REPORT` request and specifying :code:`oc:favorite` as a filter + +.. code-block:: xml + + REPORT remote.php/dav/files/user/path/to/folder + + + + 1 + + + +File properties can be requested by adding a :code:`` element to the request listing the requested properties in the same way as it would be done for a :code:`PROPFIND` request. + +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 diff --git a/developer_manual/client_apis/WebDAV/index.rst b/developer_manual/client_apis/WebDAV/index.rst index 1e22e1f0c..b147c2932 100644 --- a/developer_manual/client_apis/WebDAV/index.rst +++ b/developer_manual/client_apis/WebDAV/index.rst @@ -1,204 +1,12 @@ -.. _webdavindex: +.. _webdavapiindex: -================== -WebDAV client APIs -================== +====== +Webdav +====== -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 +.. toctree:: -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. - -Testing requests with curl --------------------------- - -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. - -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 ' - - - - - - - - - - ' - - -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 - -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. - -You can request additional properties by sending a request body with the :code:`PROPFIND` request that lists all requested properties. - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - -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. - -Getting properties for just the folder -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can request properties of a folder without also getting the folder contents by adding a :code:`Depth: 0` header to the request. - -Downloading files ------------------ - -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 - -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. - -.. code:: - - PUT remote.php/dav/files/user/path/to/file - -Any existing file will be overwritten by the request. - -Creating folders (rfc4918_) ---------------------------- - -A folder can be created by sending a :code:`MKCOL` request to the folder. - -.. code:: - - MKCOL remote.php/dav/files/user/path/to/new/folder - -Deleting files and folders (rfc4918_) -------------------------------------- - -A file or folder can be created by sending a :code:`DELETE` request to the file or folder. - -.. code:: - - DELETE remote.php/dav/files/user/path/to/file - -When deleting a folder, it's contents will be deleted recursively. - -Moving files and folders (rfc4918_) ------------------------------------ - -A file or folder can be moved by sending a :code:`MOVE` request to the file or folder and specifying the destination in the :code:`Destination` header as full url. - -.. code:: - - MOVE remote.php/dav/files/user/path/to/file - Destination: https://cloud.example/remote.php/dav/files/user/new/location - -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. - -Copying files and folders (rfc4918_) ------------------------------------- - -A file or folder can be copied by sending a :code:`COPY` request to the file or folder and specifying the destination in the :code:`Destination` header as full url. - -.. code:: - - COPY remote.php/dav/files/user/path/to/file - Destination: https://cloud.example/remote.php/dav/files/user/new/location - -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. - -Settings favorites ------------------- - -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 - -.. code-block:: xml - - PROPPATCH remote.php/dav/files/user/path/to/file - - - - - 1 - - - - -Setting the :code:`oc:favorite` property to 1 marks a file as favorite, setting it to 0 un-marks it as favorite. - -Listing favorites ------------------ - -Favorites for a user can be retrieved by sending a :code:`REPORT` request and specifying :code:`oc:favorite` as a filter - -.. code-block:: xml - - REPORT remote.php/dav/files/user/path/to/folder - - - - 1 - - - -File properties can be requested by adding a :code:`` element to the request listing the requested properties in the same way as it would be done for a :code:`PROPFIND` request. - -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 + basic + search + trashbin + versions diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst index 8f8cbb520..715719a72 100644 --- a/developer_manual/client_apis/index.rst +++ b/developer_manual/client_apis/index.rst @@ -3,44 +3,10 @@ =============================== Client APIs =============================== -Nextcloud provides an number of APIs for client applications to talk to. - - -WebDAV ------- -WebDAV is the main api for file related operations, it supports listing directories, downloading and uploading files, manipulating tags and favorites and more. - -An overview of how to use the various WebDAV APIs can be found at :doc:`WebDAV/index`, additionally Nextcloud implements rfc5323_ to allow searching the filesystem more information about how to use WebDAV search can be found at :doc:`WebDAV/search`. - -Clients can also access :doc:`WebDAV/versions` and :dock:`WebDAV/trashbin` via webdav to integrate with this. - - -OCS ---- - -The OCS API provides all information that is not available via the DAV endpoints. This contains endpoints for user data or sharing capabilities for example. See :doc:`OCS/index` for more details. - -Other OCS API documentations: - -* `Notifications API `_ -* `Notifications API - Register a device for push notifications `_ - -.. _rfc5323: _https://tools.ietf.org/html/rfc5323 - -Login Flow ----------- - -Clients can obtain an apptoken via the login flow. See :doc:`LoginFlow/index` - .. toctree:: :maxdepth: 2 - :hidden: WebDAV/index - WebDAV/search - WebDAV/trashbin - WebDAV/versions OCS/index LoginFlow/index - From d933eff701076726714cafaa51854ff0e5a18011 Mon Sep 17 00:00:00 2001 From: Roeland Jago Douma Date: Thu, 3 Jan 2019 20:43:00 +0100 Subject: [PATCH 2/3] Move chunking Signed-off-by: Roeland Jago Douma --- developer_manual/{core => client_apis/WebDAV}/chunking.rst | 0 developer_manual/client_apis/WebDAV/index.rst | 1 + developer_manual/core/index.rst | 1 - 3 files changed, 1 insertion(+), 1 deletion(-) rename developer_manual/{core => client_apis/WebDAV}/chunking.rst (100%) diff --git a/developer_manual/core/chunking.rst b/developer_manual/client_apis/WebDAV/chunking.rst similarity index 100% rename from developer_manual/core/chunking.rst rename to developer_manual/client_apis/WebDAV/chunking.rst diff --git a/developer_manual/client_apis/WebDAV/index.rst b/developer_manual/client_apis/WebDAV/index.rst index b147c2932..873e46dcc 100644 --- a/developer_manual/client_apis/WebDAV/index.rst +++ b/developer_manual/client_apis/WebDAV/index.rst @@ -10,3 +10,4 @@ Webdav search trashbin versions + chunking diff --git a/developer_manual/core/index.rst b/developer_manual/core/index.rst index 999f1b340..c1d190736 100644 --- a/developer_manual/core/index.rst +++ b/developer_manual/core/index.rst @@ -10,7 +10,6 @@ theming externalapi ocs-share-api - chunking ================= Core development From 6b3d9a36aaf8b700b18c7f080ba10e91acd56cc2 Mon Sep 17 00:00:00 2001 From: Roeland Jago Douma Date: Thu, 3 Jan 2019 20:44:31 +0100 Subject: [PATCH 3/3] Rename sections Signed-off-by: Roeland Jago Douma --- developer_manual/client_apis/WebDAV/basic.rst | 6 +++--- developer_manual/client_apis/WebDAV/chunking.rst | 6 +++--- developer_manual/client_apis/WebDAV/search.rst | 6 +++--- developer_manual/client_apis/WebDAV/trashbin.rst | 7 +++---- developer_manual/client_apis/WebDAV/versions.rst | 9 ++++----- 5 files changed, 16 insertions(+), 18 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 1e22e1f0c..35c101f8a 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -1,8 +1,8 @@ .. _webdavindex: -================== -WebDAV client APIs -================== +========== +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 diff --git a/developer_manual/client_apis/WebDAV/chunking.rst b/developer_manual/client_apis/WebDAV/chunking.rst index 4941598d4..2536b83fd 100644 --- a/developer_manual/client_apis/WebDAV/chunking.rst +++ b/developer_manual/client_apis/WebDAV/chunking.rst @@ -1,6 +1,6 @@ -============ -Chunking API -============ +=================== +Chunked file upload +=================== .. sectionauthor:: Roeland Jago Douma diff --git a/developer_manual/client_apis/WebDAV/search.rst b/developer_manual/client_apis/WebDAV/search.rst index cd03a2480..25ceb0e1d 100644 --- a/developer_manual/client_apis/WebDAV/search.rst +++ b/developer_manual/client_apis/WebDAV/search.rst @@ -1,8 +1,8 @@ .. _webdavsearch: -================== -WebDAV Search -================== +====== +Search +====== Nextcloud implements rfc5323_ WebDAV search to allow clients to search for files on the server. WebDAV search allows for fairly complex search queries with filtering and sorting on multiple properties. diff --git a/developer_manual/client_apis/WebDAV/trashbin.rst b/developer_manual/client_apis/WebDAV/trashbin.rst index 9b787174f..a2fb54dc3 100644 --- a/developer_manual/client_apis/WebDAV/trashbin.rst +++ b/developer_manual/client_apis/WebDAV/trashbin.rst @@ -1,8 +1,8 @@ .. _webdavtrashbin: -================== -WebDAV Trashbin -================== +======== +Trashbin +======== Nextcloud makes the trashbin of a user available via the webdav endpoint. @@ -41,4 +41,3 @@ Emptying the trashbin --------------------- Perform a delete on `https://cloud.example.com/remote.php/dav/trashbin/USER/trash` - diff --git a/developer_manual/client_apis/WebDAV/versions.rst b/developer_manual/client_apis/WebDAV/versions.rst index 91cfa9e23..58165fa0d 100644 --- a/developer_manual/client_apis/WebDAV/versions.rst +++ b/developer_manual/client_apis/WebDAV/versions.rst @@ -1,8 +1,8 @@ .. _webdavversions: -================== -WebDAV Versions -================== +======== +Versions +======== Nextcloud makes the versions of files available via the webdav endpoint. @@ -19,6 +19,5 @@ The name is the timestamp of the version. Restoring a version --------------------------- -To restore a version all that needs to be done is to move a version +To restore a version all that needs to be done is to move a version the special restore folder at :code:`https://cloud.example.com/remote.php/dav/versions/USER/restore` -