From 1a98f9c5055f52dc6af1b6247e581ea4e28b9d77 Mon Sep 17 00:00:00 2001 From: Roeland Jago Douma Date: Thu, 3 Jan 2019 20:41:01 +0100 Subject: [PATCH] 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 -