From 1915eed6bb0305096b26696573ddb5c70a279e38 Mon Sep 17 00:00:00 2001 From: Matthew Setter Date: Tue, 9 Jul 2019 11:26:44 +0200 Subject: [PATCH] Document The New Trash bin WebDAV API in 10.3 This commit documents the new trash bin WebDAV API to be released with ownCloud 10.3. Specifically, it documents the list, delete, and restore endpoints. It fixes #1366. --- .../trashbin_api/delete-file-from-trashbin.sh | 14 ++ .../trashbin_api/list-files-in-trashbin.sh | 29 +++ .../trashbin_api/restore-file-to-trashbin.sh | 15 ++ ...ist-files-in-trashbin-success-response.xml | 122 ++++++++++ modules/developer_manual/nav.adoc | 3 +- .../pages/webdav_api/trashbin.adoc | 230 ++++++++++++++++++ site.yml | 3 + 7 files changed, 415 insertions(+), 1 deletion(-) create mode 100644 modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/delete-file-from-trashbin.sh create mode 100644 modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/list-files-in-trashbin.sh create mode 100644 modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/restore-file-to-trashbin.sh create mode 100644 modules/developer_manual/examples/core/webdav_api/trashbin/list-files-in-trashbin-success-response.xml create mode 100644 modules/developer_manual/pages/webdav_api/trashbin.adoc diff --git a/modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/delete-file-from-trashbin.sh b/modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/delete-file-from-trashbin.sh new file mode 100644 index 0000000000..db05a3b048 --- /dev/null +++ b/modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/delete-file-from-trashbin.sh @@ -0,0 +1,14 @@ +#!/bin/bash + +## +## Variable Declaration +## +FILE_ID=11111 +USERNAME={oc-examples-username} +PASSWORD={oc-examples-password} +API_PATH="remote.php/dav/trash-bin/${USERNAME}/${FILE_ID}" +SERVER_URI="{oc-examples-server-url}" + +curl '$SERVER_URI/$API_PATH/' \ + -X DELETE \ + --user "${USERNAME}:${PASSWORD}" diff --git a/modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/list-files-in-trashbin.sh b/modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/list-files-in-trashbin.sh new file mode 100644 index 0000000000..642448d158 --- /dev/null +++ b/modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/list-files-in-trashbin.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash + +## +## Variable Declaration +## +USERNAME={oc-examples-username} +PASSWORD={oc-examples-password} +API_PATH="remote.php/dav/trash-bin/" +SERVER_URI="{oc-examples-server-url}" +REQUEST_BODY=$(cat < + + + + + + + + + +EOF +) + +curl '$SERVER_URI/$API_PATH/' \ + -H 'Content-Type: application/xml; charset=UTF-8' \ + -H 'Depth: 1' \ + -X PROPFIND \ + --data-binary "${REQUEST_BODY}" \ + --user "${USERNAME}:${PASSWORD}" diff --git a/modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/restore-file-to-trashbin.sh b/modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/restore-file-to-trashbin.sh new file mode 100644 index 0000000000..501236c3ea --- /dev/null +++ b/modules/developer_manual/examples/core/scripts/curl/dav/trashbin_api/restore-file-to-trashbin.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +## +## Variable Declaration +## +USERNAME={oc-examples-username} +PASSWORD={oc-examples-password} +API_PATH="remote.php/dav/trash-bin/${USERNAME}/${FILE_ID}" +SERVER_URI="{oc-examples-server-url}" + +curl '$SERVER_URI/$API_PATH/' \ + -H 'Overwrite: F' \ + -H 'Destination: ${SERVER_URI}/remote.php/dav/files/${USERNAME}/' \ + -X MOVE \ + --user "${USERNAME}:${PASSWORD}" diff --git a/modules/developer_manual/examples/core/webdav_api/trashbin/list-files-in-trashbin-success-response.xml b/modules/developer_manual/examples/core/webdav_api/trashbin/list-files-in-trashbin-success-response.xml new file mode 100644 index 0000000000..f003c19972 --- /dev/null +++ b/modules/developer_manual/examples/core/webdav_api/trashbin/list-files-in-trashbin-success-response.xml @@ -0,0 +1,122 @@ + + + + /remote.php/dav/trash-bin/admin/ + + + + + + + HTTP/1.1 200 OK + + + + + + + + + HTTP/1.1 404 Not Found + + + + /remote.php/dav/trash-bin/admin/255/ + + + Level 1 + Level 1 + Tue, 09 Jul 2019 08:26:38 GMT + + + + + HTTP/1.1 200 OK + + + + + + HTTP/1.1 404 Not Found + + + + /remote.php/dav/trash-bin/admin/255/256/ + + + Level 2 + Level 1/Level 2 + Tue, 09 Jul 2019 08:26:38 GMT + + + + + HTTP/1.1 200 OK + + + + + + HTTP/1.1 404 Not Found + + + + /remote.php/dav/trash-bin/admin/255/256/257/ + + + Level 3 + Level 1/Level 2/Level 3 + Tue, 09 Jul 2019 08:26:38 GMT + + + + + HTTP/1.1 200 OK + + + + + + HTTP/1.1 404 Not Found + + + + /remote.php/dav/trash-bin/admin/255/256/257/263 + + + test.txt + Level 1/Level 2/Level 3/test.txt + Tue, 09 Jul 2019 08:26:38 GMT + 34 + + + HTTP/1.1 200 OK + + + + /remote.php/dav/trash-bin/admin/123 + + + git-image-one.png + git-image-one.png + Tue, 09 Jul 2019 08:15:55 GMT + 1067792 + + + HTTP/1.1 200 OK + + + + /remote.php/dav/trash-bin/admin/119 + + + git-image-one.png + git-image-one.png + Tue, 09 Jul 2019 08:17:54 GMT + 1517914 + + + HTTP/1.1 200 OK + + + diff --git a/modules/developer_manual/nav.adoc b/modules/developer_manual/nav.adoc index 26238d53ae..e596192363 100644 --- a/modules/developer_manual/nav.adoc +++ b/modules/developer_manual/nav.adoc @@ -27,8 +27,9 @@ ***** xref:webdav_api/comments.adoc[The Comments API] ***** xref:webdav_api/groups.adoc[The Custom Groups Management 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] +***** xref:webdav_api/tags.adoc[The Tags API] +***** xref:webdav_api/trashbin.adoc[The Trash Bin API] ** xref:app/introduction.adoc[Application Development] *** xref:app/fundamentals/index.adoc[Fundamental Concepts] **** xref:app/fundamentals/info.adoc[Application Metadata] diff --git a/modules/developer_manual/pages/webdav_api/trashbin.adoc b/modules/developer_manual/pages/webdav_api/trashbin.adoc new file mode 100644 index 0000000000..02e73fc2ee --- /dev/null +++ b/modules/developer_manual/pages/webdav_api/trashbin.adoc @@ -0,0 +1,230 @@ += Trashbin API +:toc: right +:toclevels: 1 +:request-base-path: remote.php/dav/trash-bin + +== Introduction + +The trash bin API provides support for managing files in ownCloud’s trash bin. +Specifically, it provides the following functionality: + +* xref:list-files[List files in the trash bin] +* xref:delete-files[Delete files permanently from the trash bin] +* xref:restore-deleted-file[Restore deleted files to the trash bin] + +== List Files + +List all files in the trash bin + +* Path: `{request-base-path}/` +* Method: `PROPFIND` + +=== Request Parameters + +[cols=",,",options="header",] +|=== +|Attribute +|Type +|Description + +|`username` +|string +|The username of the user to list files for. +|=== + +=== Request Headers + +[cols="25%,25%,50%",options="header",] +|=== +|Header +|Type +|Description + +|`Depth` +|int +a|The maximum level to descend to, when retrieving a listing of the files in the user's trash bin. + +NOTE: Only one level of files and directories is returned if this header is omitted. +|=== + +=== Code Example + +[tabs] +==== +Curl:: ++ +-- +[source,console,subs="attributes+"] +.... +include::{examplesdir}core/scripts/curl/dav/trashbin_api/list-files-in-trashbin.sh[] +.... +-- +==== + +=== Returns + +This method returns an HTTP 207 (Multi-Status) status code and an XML response that contains the files in the trash bin of the authenticating user, limited to the depth specified by the `Depth` header. + +==== Example Response + +If the user that you’re connecting with is authorized, then you will see output similar to the following: + +[tabs] +==== +Curl:: ++ +-- +[source,xml,subs="attributes+"] +.... +include::{examplesdir}core/webdav_api/trashbin/list-files-in-trashbin-success-response.xml[] +.... +-- +==== + +== Delete Files + +Permanently delete a file from the trash bin. + +* Path: `{request-base-path}//` +* Method: `DELETE` + +=== Request Parameters + +[cols=",,",options="header",] +|=== +|Attribute +|Type +|Description + +|`username` +|string +|The username of the user to list files for. + +|`fileid` +|integer +|The id of the file to delete. +|=== + +=== Code Example + +[tabs] +==== +Curl:: ++ +-- +[source,console,subs="attributes+"] +.... +include::{examplesdir}core/scripts/curl/dav/trashbin_api/delete-file-from-trashbin.sh[] +.... +-- +==== + +=== Returns + +This method returns an HTTP 204 (No Content) status code, if the file is successfully deleted. +If there is no file in the trash bin with the specified file id, then an HTTP 404 (Not Found) status code is returned. + +== Restore Deleted File + +Restore a file from the trash bin. + +* Path: `{request-base-path}//` +* Method: `MOVE` + +=== Request Parameters + +[cols=",,",options="header",] +|=== +|Attribute +|Type +|Description + +|`username` +|string +|The username of the user to list files for. + +|`fileid` +|integer +|The id of the file to delete. +|=== + +=== Request Headers + +[cols="15%,15%,40%,30%",options="header",] +|=== +|Header +|Type +|Value +|Description + +|`Overwrite` +|string +|`F` or `T` +|Whether to overwrite an existing file. + +|`Destination` +|string +|`${SERVER_URI}/remote.php/dav/files//` +|The path where the file will be restored to. +|=== + +=== Code Example + +[tabs] +==== +Curl:: ++ +-- +[source,console,subs="attributes+"] +.... +include::{examplesdir}core/scripts/curl/dav/trashbin_api/restore-file-to-trashbin.sh[] +.... +-- +==== + +=== Returns + +==== Success + +If `Overwrite` is set to `F` and a file with the same name in the specified location does not exist, or if `Overwrite` is set to `T`, an HTTP 204 (No Content) status code will be returned, if the resource is successfully restored. + +==== File Already Exists + +If the `Overwrite` header is set to `F` and a file exists with the same name as specified in the `Destination` string, then an HTTP 412 (Precondition Failed) status code is returned, along with the following XML response: + +[source,xml] +.... + + + Sabre\DAV\Exception\PreconditionFailed + The destination node already exists, and the overwrite header is set to false + Overwrite + +.... + +==== Incorrect Overwrite Header + +If the `Overwrite` header is not set to either `T` or `F`, then an HTTP 400 (Bad Request) status code will be returned, along with the following XML response: + +[source,xml] +.... + + + Sabre\DAV\Exception\BadRequest + The HTTP Overwrite header should be either T or F + +.... + +==== Destination Directory Does Not Exist + +If the destination directory does not exist, then an HTTP 409 (Conflict) status code will be returned, along with the following XML response: + +[source,xml] +.... + + + Sabre\DAV\Exception\Conflict + The destination node is not found + +.... + diff --git a/site.yml b/site.yml index b5a51d17dd..844af4661c 100644 --- a/site.yml +++ b/site.yml @@ -50,6 +50,9 @@ asciidoc: experimental: '' latest-version: 10.2 oc-contact-url: https://owncloud.com/contact/ + oc-examples-server-url: 'https://owncloud.install.com/owncloud' + oc-examples-username: username + oc-examples-password: password occ-command-example-prefix: 'sudo -u www-data php occ' php-supported-versions-url: https://secure.php.net/supported-versions.php previous-version: 10.1