From 35eebd51b2644d59e7c11804f6256d8e744b92bd Mon Sep 17 00:00:00 2001 From: Robin Appelman Date: Thu, 9 Feb 2017 16:39:20 +0100 Subject: [PATCH 1/5] [WIP] document client api's --- developer_manual/client_apis/WebDAV/index.rst | 242 ++++++++++++++++++ developer_manual/client_apis/index.rst | 22 ++ developer_manual/index.rst | 1 + 3 files changed, 265 insertions(+) create mode 100644 developer_manual/client_apis/WebDAV/index.rst create mode 100644 developer_manual/client_apis/index.rst diff --git a/developer_manual/client_apis/WebDAV/index.rst b/developer_manual/client_apis/WebDAV/index.rst new file mode 100644 index 000000000..50070ff98 --- /dev/null +++ b/developer_manual/client_apis/WebDAV/index.rst @@ -0,0 +1,242 @@ +.. _webdavindex: + +=============================== +WebDAV Client API's +=============================== + +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}tags` +- :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://owncloud.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` + +---- +Settings tags +---- + +A file or folder can be tagged by sending a :code:`PROPPATCH` request to the file or folder and setting the :code:`oc-tags` property. + +.. code-block:: xml + + PROPPATCH remote.php/dav/files/user/path/to/file + + + + + + tag1 + tag2 + + + + + +Note that all tags for the file have to be specified, it's not possible to only specify the tags that should be added or removed. + +.. _rfc4918: https://tools.ietf.org/html/rfc4918 diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst new file mode 100644 index 000000000..41dbf60f3 --- /dev/null +++ b/developer_manual/client_apis/index.rst @@ -0,0 +1,22 @@ +.. _apiindex: + +=============================== +Client API's +=============================== +Nextcloud provides an number of api's for client applications to talk to. + + +---- +WebDAV +---- +WebDAV is the main api for file related operations, it supports listing directories, downloading an uploading files, manipulating tags and favorites and more. + +An overview of how to use the various WebDAV api's can be found at :doc:`WebDAV/index` + + +.. toctree:: + :maxdepth: 2 + :hidden: + + webdav/index + diff --git a/developer_manual/index.rst b/developer_manual/index.rst index f6472625a..33aad0ecb 100644 --- a/developer_manual/index.rst +++ b/developer_manual/index.rst @@ -17,6 +17,7 @@ Table of Contents general/index app/index android_library/index + client_apis/index core/index bugtracker/index commun/index From 1af5fbaec578d11ec7df069e157f95397107e652 Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Thu, 23 Feb 2017 22:36:16 -0600 Subject: [PATCH 2/5] document user metadata Signed-off-by: Morris Jobke --- developer_manual/client_apis/OCS/index.rst | 67 ++++++++++++++++++++++ developer_manual/client_apis/index.rst | 7 +++ 2 files changed, 74 insertions(+) create mode 100644 developer_manual/client_apis/OCS/index.rst diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst new file mode 100644 index 000000000..cf59d49bb --- /dev/null +++ b/developer_manual/client_apis/OCS/index.rst @@ -0,0 +1,67 @@ +.. _webdavindex: + +========= +OCS API's +========= + +This document provides a quick overview of the OCS API endpoints supported in Nextcloud. + +All requests need to provide authentication information, either as a Basic Auth header or by passing a set of valid session cookies, if not stated otherwise. + + +---- +Testing requests with curl +---- + +All OCS requests can be easily tested out using :code:`curl` by specifying the request method (:code:`GET`, :code:`PUT`, etc) and setting a request body where needed. + +For example: you can perform a :code:`GET` request to get information about a user: + + +.. code-block:: bash + + curl -u username:password -X GET 'https://cloud.example.com/ocs/v1.php/...' -H "OCS-APIRequest: true" + + +------------- +User metadata +------------- + +Since: 11.0.2, 12.0.0 + +This request returns the available metadata of a user. Admin users can see the information of all users, while a default user only can access it's own metadata. + +.. code:: + + GET /ocs/v1.php/cloud/users/USERID + + +.. code:: xml + + + + + ok + 100 + OK + + + + + true + + 338696790016 + 7438874 + 338704228890 + 0 + -3 + + user@foo.de + admin + +
+ + schiessle + + + diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst index 41dbf60f3..74960c0b2 100644 --- a/developer_manual/client_apis/index.rst +++ b/developer_manual/client_apis/index.rst @@ -14,9 +14,16 @@ WebDAV is the main api for file related operations, it supports listing director An overview of how to use the various WebDAV api's can be found at :doc:`WebDAV/index` +--- +OCS +--- + +The OCS API provides all information that are not available via the DAV endpoints. This contains endpoints for user data or sharing capabilities for example. See :doc:`OCS/index` for more details. + .. toctree:: :maxdepth: 2 :hidden: webdav/index + ocs/index From 397c0fa843f3ff1c1a209a4a13ecfe37eb95c4c7 Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Thu, 23 Feb 2017 22:41:15 -0600 Subject: [PATCH 3/5] notifications API Signed-off-by: Morris Jobke --- developer_manual/client_apis/index.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst index 74960c0b2..fa8021217 100644 --- a/developer_manual/client_apis/index.rst +++ b/developer_manual/client_apis/index.rst @@ -20,6 +20,11 @@ OCS The OCS API provides all information that are 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 `_ + + .. toctree:: :maxdepth: 2 :hidden: From 02dea615042a5c083cba2cdec4b82e726efe6ed7 Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Fri, 24 Feb 2017 12:26:25 -0600 Subject: [PATCH 4/5] remove documentation for tags for now Signed-off-by: Morris Jobke --- developer_manual/client_apis/WebDAV/index.rst | 25 ------------------- 1 file changed, 25 deletions(-) diff --git a/developer_manual/client_apis/WebDAV/index.rst b/developer_manual/client_apis/WebDAV/index.rst index 50070ff98..2672bded4 100644 --- a/developer_manual/client_apis/WebDAV/index.rst +++ b/developer_manual/client_apis/WebDAV/index.rst @@ -71,7 +71,6 @@ You can request additional properties by sending a request body with the :code:` - @@ -88,7 +87,6 @@ The following properties are supported: - :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}tags` - :code:`{http://owncloud.org/ns}favorite` - :code:`{http://owncloud.org/ns}comments-href` - :code:`{http://owncloud.org/ns}comments-count` @@ -216,27 +214,4 @@ File properties can be requested by adding a :code:`` element to the re 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` ----- -Settings tags ----- - -A file or folder can be tagged by sending a :code:`PROPPATCH` request to the file or folder and setting the :code:`oc-tags` property. - -.. code-block:: xml - - PROPPATCH remote.php/dav/files/user/path/to/file - - - - - - tag1 - tag2 - - - - - -Note that all tags for the file have to be specified, it's not possible to only specify the tags that should be added or removed. - .. _rfc4918: https://tools.ietf.org/html/rfc4918 From acb9988493e51873647dbe303c20be8f0f1c1831 Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Fri, 24 Feb 2017 12:28:58 -0600 Subject: [PATCH 5/5] add proper links Signed-off-by: Morris Jobke --- developer_manual/client_apis/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst index fa8021217..bc9aff355 100644 --- a/developer_manual/client_apis/index.rst +++ b/developer_manual/client_apis/index.rst @@ -22,7 +22,8 @@ The OCS API provides all information that are not available via the DAV endpoint Other OCS API documentations: -* `Notifications API `_ +* `Notifications API `_ +* `Notifications API - Register a device for push notifications `_ .. toctree::