diff --git a/modules/developer_manual/examples/core/webdav_api/search/request/filter_files/minimal_filter_files_report_request_body.xml b/modules/developer_manual/examples/core/webdav_api/search/request/filter_files/minimal_filter_files_report_request_body.xml new file mode 100644 index 0000000000..48adf88373 --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/request/filter_files/minimal_filter_files_report_request_body.xml @@ -0,0 +1,7 @@ + + + + 1 + + + diff --git a/modules/developer_manual/examples/core/webdav_api/search/request/filter_files/search_body_filtering_by_system_tag_ids.xml b/modules/developer_manual/examples/core/webdav_api/search/request/filter_files/search_body_filtering_by_system_tag_ids.xml new file mode 100644 index 0000000000..597ea85b3a --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/request/filter_files/search_body_filtering_by_system_tag_ids.xml @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + 1 + 1 + + + + diff --git a/modules/developer_manual/examples/core/webdav_api/search/request/filter_files/search_body_requesting_all_properties.xml b/modules/developer_manual/examples/core/webdav_api/search/request/filter_files/search_body_requesting_all_properties.xml new file mode 100644 index 0000000000..bcdefd3d93 --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/request/filter_files/search_body_requesting_all_properties.xml @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + 1 + + + + diff --git a/modules/developer_manual/examples/core/webdav_api/search/request/search_files/limit_number_of_results.xml b/modules/developer_manual/examples/core/webdav_api/search/request/search_files/limit_number_of_results.xml new file mode 100644 index 0000000000..f2149f7e72 --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/request/search_files/limit_number_of_results.xml @@ -0,0 +1,10 @@ + + + + web + 5 + + + diff --git a/modules/developer_manual/examples/core/webdav_api/search/request/search_files/minimal_request_body.xml b/modules/developer_manual/examples/core/webdav_api/search/request/search_files/minimal_request_body.xml new file mode 100644 index 0000000000..766287b8b7 --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/request/search_files/minimal_request_body.xml @@ -0,0 +1,9 @@ + + + + web + + + diff --git a/modules/developer_manual/examples/core/webdav_api/search/request/search_files/search_body_with_properties.xml b/modules/developer_manual/examples/core/webdav_api/search/request/search_files/search_body_with_properties.xml new file mode 100644 index 0000000000..0956a76481 --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/request/search_files/search_body_with_properties.xml @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + site + + + + diff --git a/modules/developer_manual/examples/core/webdav_api/search/response/common/failure/incorrect_payload_or_parse_failure.xml b/modules/developer_manual/examples/core/webdav_api/search/response/common/failure/incorrect_payload_or_parse_failure.xml new file mode 100644 index 0000000000..3501c845e7 --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/response/common/failure/incorrect_payload_or_parse_failure.xml @@ -0,0 +1,8 @@ + + + Sabre\Xml\ParseException + This should never happen (famous last words) + + diff --git a/modules/developer_manual/examples/core/webdav_api/search/response/common/failure/request_non_existent_property.xml b/modules/developer_manual/examples/core/webdav_api/search/response/common/failure/request_non_existent_property.xml new file mode 100644 index 0000000000..1952a64cb5 --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/response/common/failure/request_non_existent_property.xml @@ -0,0 +1,29 @@ + + + + /remote.php/dav/files/admin/Test/Sub-test/Website%20Plan.md + + + 00000065oc21s4c9iej2 + 65 + RDNVW + 423 + admin + admin + Fri, 28 Jul 2017 05:51:07 GMT + "0286fcdabf5b4f5ef84788d86c37e245" + text/markdown + + HTTP/1.1 200 OK + + + + + + HTTP/1.1 404 Not Found + + + + diff --git a/modules/developer_manual/examples/core/webdav_api/search/response/filter_files/success.xml b/modules/developer_manual/examples/core/webdav_api/search/response/filter_files/success.xml new file mode 100644 index 0000000000..c36d2adc19 --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/response/filter_files/success.xml @@ -0,0 +1,22 @@ + + + + /remote.php/dav/files/admin/welcome.txt + + + 28 + RDNVW + 163 + admin + admin + Mon, 05 Nov 2018 10:52:58 GMT + "91b08390250f5294390c4fc92b6b0138" + text/plain + + HTTP/1.1 200 OK + + + diff --git a/modules/developer_manual/examples/core/webdav_api/search/response/search_files/success/search_response.xml b/modules/developer_manual/examples/core/webdav_api/search/response/search_files/success/search_response.xml new file mode 100644 index 0000000000..1cb09e299c --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/search/response/search_files/success/search_response.xml @@ -0,0 +1,25 @@ + + + + /remote.php/dav/files/admin/Test/Sub-test/Site-Plan.md + + + 00000065oc21s4c9iej2 + + 65 + RDNVW + 423 + admin + admin + Fri, 28 Jul 2017 05:51:07 GMT + "0286fcdabf5b4f5ef84788d86c37e245" + text/markdown + + HTTP/1.1 200 OK + + + + diff --git a/modules/developer_manual/nav.adoc b/modules/developer_manual/nav.adoc index 6ba9bfaadf..50696d01e7 100644 --- a/modules/developer_manual/nav.adoc +++ b/modules/developer_manual/nav.adoc @@ -68,6 +68,7 @@ ***** xref:webdav_api/comments.adoc[The Comments API] ***** xref:webdav_api/files_versions.adoc[The Files Versions API] ***** xref:webdav_api/tags.adoc[The Tags API] +***** xref:webdav_api/search.adoc[The Search API] ** General Contributor Guidelines *** xref:general/code-of-conduct.adoc[Community Code of Conduct] *** xref:general/codingguidelines.adoc[Coding Style & General Guidelines] diff --git a/modules/developer_manual/pages/_partials/webdav_api/core_request_details.adoc b/modules/developer_manual/pages/_partials/webdav_api/core_request_details.adoc new file mode 100644 index 0000000000..6eb96716fe --- /dev/null +++ b/modules/developer_manual/pages/_partials/webdav_api/core_request_details.adoc @@ -0,0 +1,13 @@ += Core Details + +[cols=",,",options="header",] +|===================================================== +|Request Path +|Method +|Content Type + +|`{request_path}` +|{method} +|{content_type} +|===================================================== + diff --git a/modules/developer_manual/pages/_partials/webdav_api/search/common_error_responses.adoc b/modules/developer_manual/pages/_partials/webdav_api/search/common_error_responses.adoc new file mode 100644 index 0000000000..3bbb50acf0 --- /dev/null +++ b/modules/developer_manual/pages/_partials/webdav_api/search/common_error_responses.adoc @@ -0,0 +1,18 @@ +==== If The Payload File Cannot Be Read Or Is Invalid XML + +If the payload file cannot be read or is invalid XML, then the following XML response is sent, along with an `HTTP/1.1 500 Internal Server Error` status code. + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/response/common/failure/incorrect_payload_or_parse_failure.xml[indent=0] +.... + +==== If a Non-Existent Property Is Requested + +If a non-existent property is requested, then an additional `propstat` element is returned, as in the example below, which contains a list of the properties which were not available. + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/response/common/failure/request_non_existent_property.xml[indent=0,lines=19..25] +.... + diff --git a/modules/developer_manual/pages/_partials/webdav_api/search/file_properties.adoc b/modules/developer_manual/pages/_partials/webdav_api/search/file_properties.adoc new file mode 100644 index 0000000000..75e7caca08 --- /dev/null +++ b/modules/developer_manual/pages/_partials/webdav_api/search/file_properties.adoc @@ -0,0 +1,44 @@ +// Page attributes +:page-partial: + +.Available File Properties +[cols="1,3,2",options="header",] +|=== +|Property +|Description +|Namespace + +|id +|The id of the file +|`http://owncloud.org/ns` + +|permissions +|The permissions set on the file +|`http://owncloud.org/ns` + +|size +|The file's size +|`http://owncloud.org/ns` + +|owner-id +|The id of the file owner +|`http://owncloud.org/ns` + +|owner-display-name +|The display name of the file owner +|`http://owncloud.org/ns` + +|getlastmodified +|The last modified date of the file +|`DAV` + +|getetag +|The file's ETag +|`DAV` + +|getcontenttype +|The file's content type. +|`DAV` + +|=== + diff --git a/modules/developer_manual/pages/webdav_api/search.adoc b/modules/developer_manual/pages/webdav_api/search.adoc new file mode 100644 index 0000000000..9c2b6f92ca --- /dev/null +++ b/modules/developer_manual/pages/webdav_api/search.adoc @@ -0,0 +1,11 @@ += Search API + +If you need to search for files, then you can use the WebDAV search API. +The search API exposes two endpoints for finding files in a user’s filesystem; these are: + +- xref:search-files[Search Files] +- xref:filter-files[Filter Files] + +include::search/search_files.adoc[leveloffset=+1] + +include::search/filter_files.adoc[leveloffset=+1] diff --git a/modules/developer_manual/pages/webdav_api/search/filter_files.adoc b/modules/developer_manual/pages/webdav_api/search/filter_files.adoc new file mode 100644 index 0000000000..3675c07ecc --- /dev/null +++ b/modules/developer_manual/pages/webdav_api/search/filter_files.adoc @@ -0,0 +1,118 @@ +[[filter-files]] += Filter Files +// Page attributes +:page-partial: +// Attributes for the core details include +:request_path: remote.php/dav/files/ +:method: REPORT +:content_type: text/xml + +The `filter-files` report allows for retrieving a list of files in an ownCloud user's filesystem, based on two criteria: + +include::{partialsdir}/webdav_api/core_request_details.adoc[leveloffset=+1] + +== The Request + +An authenticated https://tools.ietf.org/html/rfc3253#section-3.6[REPORT request] needs to be made to retrieve a list of all files stored in a user's ownCloud filesystem. + +=== Example Request + +[source,console] +.... +curl --silent \ + -X REPORT \ + --data "@filter-files-criteria.xml" \ + -u admin:admin \ + 'http://localhost/remote.php/dav/files/admin' | xmllint --format - +.... + +The request must include a request body that includes the rules to filter by. +There are two filter rules which can be supplied; these are: + +[cols="1,2,1,1,1",options="header",] +|=== +|Rule +|Description +|Type +|Accepted Values +|Mandatory + +|`favorite` +|Whether they’ve been marked as a favorite or not (mandatory) +|integer +|`0`,`1` +|Yes + +|`systemtag` +|The tags that have been assigned to them +|integer +|Any valid system tag. + These can be retrieved by using xref:webdav_api/tags.adoc#list-tags[the Tags API]. +|No +|=== + +=== Example Request Bodies + +Below, are several examples of the XML response bodies that can be sent with the request. + +==== Minimal Request Body + +In the `search` element, it specifies the search pattern to filter down the list of files to return in a successful resultset. + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/request/filter_files/minimal_filter_files_report_request_body.xml[indent=0] +.... + +==== Limiting Returned File Properties + +If only a specific list of properties is required for each file, then a `prop` element needs to be included in the response body, such as in the example below. + +include::{partialsdir}/webdav_api/search/file_properties.adoc[] + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/request/filter_files/search_body_requesting_all_properties.xml[indent=0] +.... + +==== Filtering By Tag + +Files can be filtered by those assigned specific tags. +If this is required, then the `systemtag` element needs to be supplied, which contains a space-separated list of tag _ids_ to filter by. + +TIP: Tag ids can be retrieved by using xref:webdav_api/tags.adoc#list-tags[the Tags API]. + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/request/filter_files/search_body_filtering_by_system_tag_ids.xml[indent=0] +.... + +NOTE: The example uses http://xmlsoft.org/xmllint.html[xmllint] to make the response more readable. +Xmllint is available in the http://www.xmlsoft.org/[libxml2 package]. + +== The Response + +=== Success + +Successful requests return two things: + +. An XML payload. +. A status of `HTTP/1.1 207 Multi-Status`. + +You can see an example of the XML payload below. +The XML payload contains a `response` element for each file. +And each `response` element contains three items: + +. A link to the file (`href`). +. The requested properties, along with their respective values (`propstat`). +. The file's status (`status`). + +.Example of a successful search response +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/response/filter_files/success.xml[indent=0] +.... + +=== Failure + +include::{partialsdir}/webdav_api/search/common_error_responses.adoc[] diff --git a/modules/developer_manual/pages/webdav_api/search/search_files.adoc b/modules/developer_manual/pages/webdav_api/search/search_files.adoc new file mode 100644 index 0000000000..a563799975 --- /dev/null +++ b/modules/developer_manual/pages/webdav_api/search/search_files.adoc @@ -0,0 +1,117 @@ +[[search-files]] += Search Files +// Page attributes +:page-partial: +// Attributes for the core details include +:request_path: remote.php/dav/files/ +:method: REPORT +:content_type: text/xml + +The `search-files` report search through the available files in an ownCloud user's filesystem, based on a rudimentary filename pattern match. + +By default, the report uses ownCloud's default search provider to power the search functionality. +However, other search providers, such as link:https://github.com/owncloud/search_elastic[search_elastic] and link:https://github.com/owncloudarchive/search_lucene[search_lucene] greatly enrich the ability to search, such as being able to search through file content, as well as by a file's name. +When installed, they replace ownCloud's default search provider and the search API will automatically use them. + +TIP: When using the default search provider, if you use the search string "_ownCloud_", files whose filename has "ownCloud" in it will be matched. +However, if installed link:https://github.com/owncloud/search_elastic[the search_elastic app], the report also retrieves files that have "_ownCloud_" in the file's contents. + +include::{partialsdir}/webdav_api/core_request_details.adoc[leveloffset=+1] + +== The Request + +An authenticated https://tools.ietf.org/html/rfc3253#section-3.6[REPORT request] needs to be made to search for all files stored in a user's ownCloud filesystem + +=== Example Request + +[source,console] +.... +curl --silent \ + -X REPORT \ + --data "@supported.xml" \ + -u admin:admin \ + 'http://localhost/remote.php/dav/files/admin' | xmllint --format - +.... + +The request must include a request body that includes the search pattern, and can also include a list of properties to return. + +=== Example Request Bodies + +Below, are several examples of XML response bodies. + +==== Filtering By Filename Pattern + +In the `search` element, specify the search pattern to filter the list of files to return. + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/request/search_files/minimal_request_body.xml[indent=0] +.... + +==== Limiting The Number Of Results Returned + +To limit the number of results returned, use the `limit` element of the `search` element, as in the following example. +It will limit the maximum number of results returned to five. + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/request/search_files/limit_number_of_results.xml[indent=0] +.... + +==== Reducing The File Properties Returned + +However, if a specific list of properties is required for each file, then a `prop` element needs to be included in the response body, such as in the example below. + +include::{partialsdir}/webdav_api/search/file_properties.adoc[] + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/request/search_files/search_body_with_properties.xml[indent=0] +.... + +NOTE: The example uses http://xmlsoft.org/xmllint.html[xmllint] to make the response more readable. +Xmllint is available in the http://www.xmlsoft.org/[libxml2 package]. + +== The Response + +=== Success + +Successful requests return two things: + +. An XML payload. +. A status of `HTTP/1.1 207 Multi-Status`. + +You can see an example of the XML payload below. +The XML payload contains a `response` element for each file. +And each `response` element contains three items: + +. A link to the file (`href`). +. The requested properties, along with their respective values (`propstat`). +. The file's status (`status`). + +.Search Response +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/response/search_files/success/search_response.xml[indent=0] +.... + +=== Failure + +==== If The Payload File Cannot Be Read Or Is Invalid XML + +If the payload file cannot be read or is invalid XML, then the following XML response is sent, along with an `HTTP/1.1 500 Internal Server Error` status code. + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/response/common/failure/incorrect_payload_or_parse_failure.xml[indent=0] +.... + +==== If a Non-Existent Property Is Requested + +If a non-existent property is requested, then an additional `propstat` element is returned, as in the example below, which contains a list of the properties which were not available. + +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/response/common/failure/request_non_existent_property.xml[indent=0,lines=19..25] +.... +