diff --git a/developer_manual/client_apis/WebDAV/search.rst b/developer_manual/client_apis/WebDAV/search.rst new file mode 100644 index 000000000..cb8bbf3d4 --- /dev/null +++ b/developer_manual/client_apis/WebDAV/search.rst @@ -0,0 +1,215 @@ +.. _webdavsearch: + +================== +WebDAV 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. + +This document describes how to use WebDAV search with a Nextcloud server and provides some example queries, +full details of the api can be found at rfc5323_. + +Making search requests +---------------------- + +Search requests can be made by sending a :code:`SEARCH` http request to :code:`cloud.example.com/remote.php/dav` +with a content type of :code:`text/xml` and the query as xml in the request body. + +For example, to search for text files for the user 'test': + +.. code-block:: bash + + curl -u username:password 'https://cloud.example.com/remote.php/dav/files/username/folder' -X SEARCH -u test:test -H "content-Type: text/xml" --data ' + + + + + + + + + + + + + + /files/test + infinity + + + + + + + + text/% + + + + + ' + +Supported DAV properties +------------------------ + +The following DAV properties are supported for use in either :code:`select`, :code:`where` and :code:`orderby`, +not all properties can be used for each operation. + ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| Property name | Description | Selectable | Searchable | Sortable | Type | ++==============================================+=================================+============+============+==========+==========+ +| {DAV:}displayname | File name | ✓ | ✓ | ✓ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {DAV:}getcontenttype | Mime type | ✓ | ✓ | ✓ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {DAV:}getlastmodified | Modified date | ✓ | ✓ | ✓ | Datetime | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {http://owncloud.org/ns}size | File size or folder size | ✓ | ✓ | ✓ | Integer | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {http://owncloud.org/ns}favorite | Favorite status | ✓ | ✓ | ✓ | Boolean | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {http://owncloud.org/ns}fileid | Nextcloud file id | ✓ | ✓ |❌ | Integer | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {DAV:}resourcetype | File or folder | ✓ |❌ |❌ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {DAV:}getcontentlength | File size, not for folders | ✓ |❌ |❌ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {http://owncloud.org/ns}checksums | Stored checksums for the file | ✓ |❌ |❌ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {http://owncloud.org/ns}permissions | File permissions | ✓ |❌ |❌ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {DAV:}getetag | File etag | ✓ |❌ |❌ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {http://owncloud.org/ns}owner-id | File owner | ✓ |❌ |❌ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {http://owncloud.org/ns}owner-display-name | File owner display name | ✓ |❌ |❌ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {http://owncloud.org/ns}data-fingerprint | Fingerprint for recovery status | ✓ |❌ |❌ | String | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ +| {http://nextcloud.org/ns}has-preview | Preview status | ✓ |❌ |❌ | Boolean | ++----------------------------------------------+---------------------------------+------------+------------+----------+----------+ + +Search scope +------------ + +All search queries are scoped to a single folder relative to the dav root. +At the moment only search queries for files are supported meaning the the scope should always start with :code:`files/$username`. + +Inside the user's files, any existing folder can be used as search scope. + +Examples search bodies +---------------------- + +Search for all plain text files in the folder :code:`Documents`, sorted by size. + +.. code-block:: xml + + + + + + + + + + + + /files/test/Documents + infinity + + + + + + + + text/% + + + + + + + + + + + +Get a file by id. + +.. code-block:: xml + + + + + + + + + + + + /files/test + infinity + + + + + + + + 12345 + + + + + + +Get all png and jpg files over 10MB. + +.. code-block:: xml + + + + + + + + + + + + /files/test + infinity + + + + + + + + + + image/png + + + + + + image/jpg + + + + + + + 10000000 + + + + + + + +.. _rfc5323: _https://tools.ietf.org/html/rfc5323 diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst index 4583a9a56..09a2aa324 100644 --- a/developer_manual/client_apis/index.rst +++ b/developer_manual/client_apis/index.rst @@ -11,7 +11,8 @@ 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` +An overview of how to use the various WebDAV api's 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`. --- @@ -25,6 +26,7 @@ Other OCS API documentations: * `Notifications API `_ * `Notifications API - Register a device for push notifications `_ +.. _rfc5323: _https://tools.ietf.org/html/rfc5323 Login Flow ----------