From 205b029b82a0cd98e178947ccf4ee666ef572a3c Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Tue, 13 Nov 2018 10:07:23 +0100 Subject: [PATCH 1/5] Link to the search api documentation in the navigation --- modules/developer_manual/nav.adoc | 1 + 1 file changed, 1 insertion(+) 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] From de4236c2217281016c964bba62914ef95f7a2c4c Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Tue, 13 Nov 2018 14:09:45 +0100 Subject: [PATCH 2/5] Document the WebDAV search-files Search API endpoint This relates to https://github.com/owncloud/core/pull/31873 and documents the search-files report of ownCloud's Search API. --- .../search/request/minimal_request_body.xml | 9 ++ .../incorrect_payload_or_parse_failure.xml | 8 ++ .../failure/request_non_existent_property.xml | 29 ++++ .../responses/success/search_response.xml | 25 ++++ .../search/search_body_with_properties.xml | 22 +++ .../webdav_api/core_request_details.adoc | 13 ++ .../_partials/webdav_api/search_api.adoc | 0 .../pages/webdav_api/search.adoc | 8 ++ .../pages/webdav_api/search/search_files.adoc | 133 ++++++++++++++++++ 9 files changed, 247 insertions(+) create mode 100644 modules/developer_manual/examples/core/apis/search/request/minimal_request_body.xml create mode 100644 modules/developer_manual/examples/core/apis/search/responses/failure/incorrect_payload_or_parse_failure.xml create mode 100644 modules/developer_manual/examples/core/apis/search/responses/failure/request_non_existent_property.xml create mode 100644 modules/developer_manual/examples/core/apis/search/responses/success/search_response.xml create mode 100644 modules/developer_manual/examples/core/apis/search/search_body_with_properties.xml create mode 100644 modules/developer_manual/pages/_partials/webdav_api/core_request_details.adoc create mode 100644 modules/developer_manual/pages/_partials/webdav_api/search_api.adoc create mode 100644 modules/developer_manual/pages/webdav_api/search.adoc create mode 100644 modules/developer_manual/pages/webdav_api/search/search_files.adoc diff --git a/modules/developer_manual/examples/core/apis/search/request/minimal_request_body.xml b/modules/developer_manual/examples/core/apis/search/request/minimal_request_body.xml new file mode 100644 index 0000000000..766287b8b7 --- /dev/null +++ b/modules/developer_manual/examples/core/apis/search/request/minimal_request_body.xml @@ -0,0 +1,9 @@ + + + + web + + + diff --git a/modules/developer_manual/examples/core/apis/search/responses/failure/incorrect_payload_or_parse_failure.xml b/modules/developer_manual/examples/core/apis/search/responses/failure/incorrect_payload_or_parse_failure.xml new file mode 100644 index 0000000000..3501c845e7 --- /dev/null +++ b/modules/developer_manual/examples/core/apis/search/responses/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/apis/search/responses/failure/request_non_existent_property.xml b/modules/developer_manual/examples/core/apis/search/responses/failure/request_non_existent_property.xml new file mode 100644 index 0000000000..1952a64cb5 --- /dev/null +++ b/modules/developer_manual/examples/core/apis/search/responses/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/apis/search/responses/success/search_response.xml b/modules/developer_manual/examples/core/apis/search/responses/success/search_response.xml new file mode 100644 index 0000000000..1cb09e299c --- /dev/null +++ b/modules/developer_manual/examples/core/apis/search/responses/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/examples/core/apis/search/search_body_with_properties.xml b/modules/developer_manual/examples/core/apis/search/search_body_with_properties.xml new file mode 100644 index 0000000000..0956a76481 --- /dev/null +++ b/modules/developer_manual/examples/core/apis/search/search_body_with_properties.xml @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + site + + + + 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_api.adoc b/modules/developer_manual/pages/_partials/webdav_api/search_api.adoc new file mode 100644 index 0000000000..e69de29bb2 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..49aa2987c0 --- /dev/null +++ b/modules/developer_manual/pages/webdav_api/search.adoc @@ -0,0 +1,8 @@ += 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] + +include::search/search_files.adoc[leveloffset=+1] 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..e451608719 --- /dev/null +++ b/modules/developer_manual/pages/webdav_api/search/search_files.adoc @@ -0,0 +1,133 @@ +[[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 allows for searching the available files in an ownCloud user's filesystem, based on a rudimentary filename pattern match. + +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. +Below, is an example of the most basic XML response 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/apis/search/request/minimal_request_body.xml[indent=0] +.... + +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. + +.Available Properties +[cols="1,3",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` + +|=== + + +.supported.xml +[source,xml] +.... +include::{examplesdir}/core/apis/search/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/apis/search/responses/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/apis/search/responses/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/apis/search/responses/failure/request_non_existent_property.xml[indent=0,lines=19..25] +.... + From 740d3bdacb48391695408dbb7d2f0c2ca98686b8 Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Wed, 14 Nov 2018 14:14:36 +0100 Subject: [PATCH 3/5] Reorganise webdav search api documentation file structure Before, the file organisation was descending into a mess, so it needed to be stopped and fixed before it became complete chaos. This commit does that. --- ...nimal_filter_files_report_request_body.xml | 7 +++ ...earch_body_filtering_by_system_tag_ids.xml | 19 ++++++++ .../search_body_requesting_all_properties.xml | 18 ++++++++ .../search_files/limit_number_of_results.xml | 10 +++++ .../search_files}/minimal_request_body.xml | 0 .../search_body_with_properties.xml | 0 .../incorrect_payload_or_parse_failure.xml | 0 .../failure/request_non_existent_property.xml | 0 .../search/response/filter_files/success.xml | 22 ++++++++++ .../search_files}/success/search_response.xml | 0 .../search/common_error_responses.adoc | 18 ++++++++ .../webdav_api/search/file_properties.adoc | 44 +++++++++++++++++++ .../_partials/webdav_api/search_api.adoc | 0 13 files changed, 138 insertions(+) create mode 100644 modules/developer_manual/examples/core/webdav_api/search/request/filter_files/minimal_filter_files_report_request_body.xml create mode 100644 modules/developer_manual/examples/core/webdav_api/search/request/filter_files/search_body_filtering_by_system_tag_ids.xml create mode 100644 modules/developer_manual/examples/core/webdav_api/search/request/filter_files/search_body_requesting_all_properties.xml create mode 100644 modules/developer_manual/examples/core/webdav_api/search/request/search_files/limit_number_of_results.xml rename modules/developer_manual/examples/core/{apis/search/request => webdav_api/search/request/search_files}/minimal_request_body.xml (100%) rename modules/developer_manual/examples/core/{apis/search => webdav_api/search/request/search_files}/search_body_with_properties.xml (100%) rename modules/developer_manual/examples/core/{apis/search/responses => webdav_api/search/response/common}/failure/incorrect_payload_or_parse_failure.xml (100%) rename modules/developer_manual/examples/core/{apis/search/responses => webdav_api/search/response/common}/failure/request_non_existent_property.xml (100%) create mode 100644 modules/developer_manual/examples/core/webdav_api/search/response/filter_files/success.xml rename modules/developer_manual/examples/core/{apis/search/responses => webdav_api/search/response/search_files}/success/search_response.xml (100%) create mode 100644 modules/developer_manual/pages/_partials/webdav_api/search/common_error_responses.adoc create mode 100644 modules/developer_manual/pages/_partials/webdav_api/search/file_properties.adoc delete mode 100644 modules/developer_manual/pages/_partials/webdav_api/search_api.adoc 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/apis/search/request/minimal_request_body.xml b/modules/developer_manual/examples/core/webdav_api/search/request/search_files/minimal_request_body.xml similarity index 100% rename from modules/developer_manual/examples/core/apis/search/request/minimal_request_body.xml rename to modules/developer_manual/examples/core/webdav_api/search/request/search_files/minimal_request_body.xml diff --git a/modules/developer_manual/examples/core/apis/search/search_body_with_properties.xml b/modules/developer_manual/examples/core/webdav_api/search/request/search_files/search_body_with_properties.xml similarity index 100% rename from modules/developer_manual/examples/core/apis/search/search_body_with_properties.xml rename to modules/developer_manual/examples/core/webdav_api/search/request/search_files/search_body_with_properties.xml diff --git a/modules/developer_manual/examples/core/apis/search/responses/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 similarity index 100% rename from modules/developer_manual/examples/core/apis/search/responses/failure/incorrect_payload_or_parse_failure.xml rename to modules/developer_manual/examples/core/webdav_api/search/response/common/failure/incorrect_payload_or_parse_failure.xml diff --git a/modules/developer_manual/examples/core/apis/search/responses/failure/request_non_existent_property.xml b/modules/developer_manual/examples/core/webdav_api/search/response/common/failure/request_non_existent_property.xml similarity index 100% rename from modules/developer_manual/examples/core/apis/search/responses/failure/request_non_existent_property.xml rename to modules/developer_manual/examples/core/webdav_api/search/response/common/failure/request_non_existent_property.xml 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/apis/search/responses/success/search_response.xml b/modules/developer_manual/examples/core/webdav_api/search/response/search_files/success/search_response.xml similarity index 100% rename from modules/developer_manual/examples/core/apis/search/responses/success/search_response.xml rename to modules/developer_manual/examples/core/webdav_api/search/response/search_files/success/search_response.xml 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/_partials/webdav_api/search_api.adoc b/modules/developer_manual/pages/_partials/webdav_api/search_api.adoc deleted file mode 100644 index e69de29bb2..0000000000 From 34be791df61e09fbd86accfe62cdb473b868a122 Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Wed, 14 Nov 2018 14:15:39 +0100 Subject: [PATCH 4/5] Document WebDAV Search API filter-files report --- .../pages/webdav_api/search.adoc | 3 + .../pages/webdav_api/search/filter_files.adoc | 118 ++++++++++++++++++ .../pages/webdav_api/search/search_files.adoc | 67 ++++------ 3 files changed, 143 insertions(+), 45 deletions(-) create mode 100644 modules/developer_manual/pages/webdav_api/search/filter_files.adoc diff --git a/modules/developer_manual/pages/webdav_api/search.adoc b/modules/developer_manual/pages/webdav_api/search.adoc index 49aa2987c0..9c2b6f92ca 100644 --- a/modules/developer_manual/pages/webdav_api/search.adoc +++ b/modules/developer_manual/pages/webdav_api/search.adoc @@ -4,5 +4,8 @@ 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 index e451608719..818fa231fb 100644 --- a/modules/developer_manual/pages/webdav_api/search/search_files.adoc +++ b/modules/developer_manual/pages/webdav_api/search/search_files.adoc @@ -27,62 +27,39 @@ curl --silent \ .... The request must include a request body that includes the search pattern, and can also include a list of properties to return. -Below, is an example of the most basic XML response 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/apis/search/request/minimal_request_body.xml[indent=0] -.... +=== Example Request Bodies -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. +Below, are several examples of XML response bodies. -.Available Properties -[cols="1,3",options="header",] -|=== -|Property -|Description -|Namespace +==== Filtering By Filename Pattern -|id -|The id of the file -|`http://owncloud.org/ns` +In the `search` element, specify the search pattern to filter the list of files to return. -|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` +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/request/search_files/minimal_request_body.xml[indent=0] +.... -|owner-display-name -|The display name of the file owner -|`http://owncloud.org/ns` +==== Limiting The Number Of Results Returned -|getlastmodified -|The last modified date of the file -|`DAV` +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. -|getetag -|The file's ETag -|`DAV` +[source,xml] +.... +include::{examplesdir}/core/webdav_api/search/request/search_files/limit_number_of_results.xml[indent=0] +.... -|getcontenttype -|The file's content type. -|`DAV` +==== 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[] -.supported.xml [source,xml] .... -include::{examplesdir}/core/apis/search/search_body_with_properties.xml[indent=0] +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. @@ -108,7 +85,7 @@ And each `response` element contains three items: .Search Response [source,xml] .... -include::{examplesdir}/core/apis/search/responses/success/search_response.xml[indent=0] +include::{examplesdir}/core/webdav_api/search/response/search_files/success/search_response.xml[indent=0] .... === Failure @@ -119,7 +96,7 @@ If the payload file cannot be read or is invalid XML, then the following XML res [source,xml] .... -include::{examplesdir}/core/apis/search/responses/failure/incorrect_payload_or_parse_failure.xml[indent=0] +include::{examplesdir}/core/webdav_api/search/response/common/failure/incorrect_payload_or_parse_failure.xml[indent=0] .... ==== If a Non-Existent Property Is Requested @@ -128,6 +105,6 @@ If a non-existent property is requested, then an additional `propstat` element i [source,xml] .... -include::{examplesdir}/core/apis/search/responses/failure/request_non_existent_property.xml[indent=0,lines=19..25] +include::{examplesdir}/core/webdav_api/search/response/common/failure/request_non_existent_property.xml[indent=0,lines=19..25] .... From ff3e1ed2e07e3d8be34f4c5c8f6982e4a9c9a9d9 Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Fri, 16 Nov 2018 11:03:26 +0100 Subject: [PATCH 5/5] Add a note about functionality provided by additional search apps This commit adds a note about the functionality that search apps provide over the default search provider. --- .../pages/webdav_api/search/search_files.adoc | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/modules/developer_manual/pages/webdav_api/search/search_files.adoc b/modules/developer_manual/pages/webdav_api/search/search_files.adoc index 818fa231fb..a563799975 100644 --- a/modules/developer_manual/pages/webdav_api/search/search_files.adoc +++ b/modules/developer_manual/pages/webdav_api/search/search_files.adoc @@ -7,7 +7,14 @@ :method: REPORT :content_type: text/xml -The search-files report allows for searching the available files in an ownCloud user's filesystem, based on a rudimentary filename pattern match. +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]