mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-02 17:59:36 +07:00
Merge pull request #351 from nextcloud/client-apis
document client api's
This commit is contained in:
Morris Jobke
67
developer_manual/client_apis/OCS/index.rst
Normal file
67
developer_manual/client_apis/OCS/index.rst
Normal file
@@ -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
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<ocs>
|
||||
<meta>
|
||||
<status>ok</status>
|
||||
<statuscode>100</statuscode>
|
||||
<message>OK</message>
|
||||
<totalitems></totalitems>
|
||||
<itemsperpage></itemsperpage>
|
||||
</meta>
|
||||
<data>
|
||||
<enabled>true</enabled>
|
||||
<quota>
|
||||
<free>338696790016</free>
|
||||
<used>7438874</used>
|
||||
<total>338704228890</total>
|
||||
<relative>0</relative>
|
||||
<quota>-3</quota>
|
||||
</quota>
|
||||
<email>user@foo.de</email>
|
||||
<displayname>admin</displayname>
|
||||
<phone></phone>
|
||||
<address></address>
|
||||
<webpage></webpage>
|
||||
<twitter>schiessle</twitter>
|
||||
</data>
|
||||
</ocs>
|
||||
|
||||
217
developer_manual/client_apis/WebDAV/index.rst
Normal file
217
developer_manual/client_apis/WebDAV/index.rst
Normal file
@@ -0,0 +1,217 @@
|
||||
.. _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 '<?xml version="1.0" encoding="UTF-8"?>
|
||||
<d:propfind xmlns:d="DAV:">
|
||||
<d:prop xmlns:oc="http://owncloud.org/ns">
|
||||
<d:getlastmodified/>
|
||||
<d:getcontentlength/>
|
||||
<d:getcontenttype/>
|
||||
<oc:permissions/>
|
||||
<d:resourcetype/>
|
||||
<d:getetag/>
|
||||
</d:prop>
|
||||
</d:propfind>'
|
||||
|
||||
|
||||
----
|
||||
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
|
||||
|
||||
<?xml version="1.0"?>
|
||||
<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
|
||||
<d:prop>
|
||||
<d:getlastmodified />
|
||||
<d:getetag />
|
||||
<d:getcontenttype />
|
||||
<d:resourcetype />
|
||||
<oc:fileid />
|
||||
<oc:permissions />
|
||||
<oc:size />
|
||||
<d:getcontentlength />
|
||||
<nc:has-preview />
|
||||
<oc:favorite />
|
||||
<oc:comments-unread />
|
||||
<oc:owner-display-name />
|
||||
<oc:share-types />
|
||||
</d:prop>
|
||||
</d:propfind>
|
||||
|
||||
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://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
|
||||
<?xml version="1.0"?>
|
||||
<d:propertyupdate xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">
|
||||
<d:set>
|
||||
<d:prop>
|
||||
<oc:favorite>1</oc:favorite>
|
||||
</d:prop>
|
||||
</d:set>
|
||||
</d:propertyupdate>
|
||||
|
||||
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
|
||||
<?xml version="1.0"?>
|
||||
<oc:filter-files xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
|
||||
<oc:filter-rules>
|
||||
<oc:favorite>1</oc:favorite>
|
||||
</oc:filter-rules>
|
||||
</oc:filter-files>
|
||||
|
||||
File properties can be requested by adding a :code:`<d:prop/>` 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
|
||||
35
developer_manual/client_apis/index.rst
Normal file
35
developer_manual/client_apis/index.rst
Normal file
@@ -0,0 +1,35 @@
|
||||
.. _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`
|
||||
|
||||
|
||||
---
|
||||
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 <https://github.com/nextcloud/notifications/blob/master/docs/ocs-endpoint-v2.md>`_
|
||||
* `Notifications API - Register a device for push notifications <https://github.com/nextcloud/notifications/blob/5a2d3607952bad675e4057620a9c7de8a7f84f0b/docs/push-v3.md>`_
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:hidden:
|
||||
|
||||
webdav/index
|
||||
ocs/index
|
||||
|
||||
@@ -17,6 +17,7 @@ Table of Contents
|
||||
general/index
|
||||
app/index
|
||||
android_library/index
|
||||
client_apis/index
|
||||
core/index
|
||||
bugtracker/index
|
||||
commun/index
|
||||
|
||||
Reference in New Issue
Block a user