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 332d59820b..e20ae684c1 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