Trashbin API
Introduction
The trash bin API provides support for managing files in ownCloud’s trash bin. Specifically, it provides the following functionality:
List Files
List all files in the trash bin
-
Path:
remote.php/dav/trash-bin/<username>
-
Method:
PROPFIND
Request Parameters
Attribute | Type | Description |
---|---|---|
|
string |
The username of the user to list files for. |
Request Headers
Header | Type | Description | ||
---|---|---|---|---|
|
int |
The maximum level to descend to, when retrieving a listing of the files in the user’s trash bin.
|
Code Example
#!/usr/bin/env bash
##
## Variable Declaration
##
USERNAME=username
PASSWORD=password
API_PATH="remote.php/dav/trash-bin/<username>"
SERVER_URI="https://owncloud.install.com/owncloud"
REQUEST_BODY=$(cat <<EOF
<?xml version="1.0"?>
<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">
<d:prop>
<oc:trashbin-original-filename />
<oc:trashbin-original-location />
<oc:trashbin-delete-datetime />
<d:getcontentlength />
<d:resourcetype />
</d:prop>
</d:propfind>
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"
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:
<?xml version="1.0"?>
<d:multistatus xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns" xmlns:oc="http://owncloud.org/ns">
<d:response>
<d:href>/remote.php/dav/trash-bin/admin/</d:href>
<d:propstat>
<d:prop>
<d:resourcetype>
<d:collection/>
</d:resourcetype>
</d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
<d:propstat>
<d:prop>
<oc:trashbin-original-filename/>
<oc:trashbin-original-location/>
<oc:trashbin-delete-datetime/>
<d:getcontentlength/>
</d:prop>
<d:status>HTTP/1.1 404 Not Found</d:status>
</d:propstat>
</d:response>
<d:response>
<d:href>/remote.php/dav/trash-bin/admin/255/</d:href>
<d:propstat>
<d:prop>
<oc:trashbin-original-filename>Level 1</oc:trashbin-original-filename>
<oc:trashbin-original-location>Level 1</oc:trashbin-original-location>
<oc:trashbin-delete-datetime>Tue, 09 Jul 2019 08:26:38 GMT</oc:trashbin-delete-datetime>
<d:resourcetype>
<d:collection/>
</d:resourcetype>
</d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
<d:propstat>
<d:prop>
<d:getcontentlength/>
</d:prop>
<d:status>HTTP/1.1 404 Not Found</d:status>
</d:propstat>
</d:response>
<d:response>
<d:href>/remote.php/dav/trash-bin/admin/255/256/</d:href>
<d:propstat>
<d:prop>
<oc:trashbin-original-filename>Level 2</oc:trashbin-original-filename>
<oc:trashbin-original-location>Level 1/Level 2</oc:trashbin-original-location>
<oc:trashbin-delete-datetime>Tue, 09 Jul 2019 08:26:38 GMT</oc:trashbin-delete-datetime>
<d:resourcetype>
<d:collection/>
</d:resourcetype>
</d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
<d:propstat>
<d:prop>
<d:getcontentlength/>
</d:prop>
<d:status>HTTP/1.1 404 Not Found</d:status>
</d:propstat>
</d:response>
<d:response>
<d:href>/remote.php/dav/trash-bin/admin/255/256/257/</d:href>
<d:propstat>
<d:prop>
<oc:trashbin-original-filename>Level 3</oc:trashbin-original-filename>
<oc:trashbin-original-location>Level 1/Level 2/Level 3</oc:trashbin-original-location>
<oc:trashbin-delete-datetime>Tue, 09 Jul 2019 08:26:38 GMT</oc:trashbin-delete-datetime>
<d:resourcetype>
<d:collection/>
</d:resourcetype>
</d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
<d:propstat>
<d:prop>
<d:getcontentlength/>
</d:prop>
<d:status>HTTP/1.1 404 Not Found</d:status>
</d:propstat>
</d:response>
<d:response>
<d:href>/remote.php/dav/trash-bin/admin/255/256/257/263</d:href>
<d:propstat>
<d:prop>
<oc:trashbin-original-filename>test.txt</oc:trashbin-original-filename>
<oc:trashbin-original-location>Level 1/Level 2/Level 3/test.txt</oc:trashbin-original-location>
<oc:trashbin-delete-datetime>Tue, 09 Jul 2019 08:26:38 GMT</oc:trashbin-delete-datetime>
<d:getcontentlength>34</d:getcontentlength>
<d:resourcetype/>
</d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
</d:response>
<d:response>
<d:href>/remote.php/dav/trash-bin/admin/123</d:href>
<d:propstat>
<d:prop>
<oc:trashbin-original-filename>git-image-one.png</oc:trashbin-original-filename>
<oc:trashbin-original-location>git-image-one.png</oc:trashbin-original-location>
<oc:trashbin-delete-datetime>Tue, 09 Jul 2019 08:15:55 GMT</oc:trashbin-delete-datetime>
<d:getcontentlength>1067792</d:getcontentlength>
<d:resourcetype/>
</d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
</d:response>
<d:response>
<d:href>/remote.php/dav/trash-bin/admin/119</d:href>
<d:propstat>
<d:prop>
<oc:trashbin-original-filename>git-image-one.png</oc:trashbin-original-filename>
<oc:trashbin-original-location>git-image-one.png</oc:trashbin-original-location>
<oc:trashbin-delete-datetime>Tue, 09 Jul 2019 08:17:54 GMT</oc:trashbin-delete-datetime>
<d:getcontentlength>1517914</d:getcontentlength>
<d:resourcetype/>
</d:prop>
<d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
</d:response>
</d:multistatus>
Delete Files
Restore Deleted File
Restore a file from the trash bin.
-
Path:
remote.php/dav/trash-bin/<username>/<fileid>
-
Method:
MOVE
Request Parameters
Attribute | Type | Description |
---|---|---|
|
string |
The username of the user to list files for. |
|
integer |
The id of the file to delete. |
Request Headers
Header | Type | Value | Description |
---|---|---|---|
|
string |
|
Whether to overwrite an existing file. |
|
string |
|
The path where the file will be restored to. |
Code Example
#!/bin/bash
##
## Variable Declaration
##
FILE_ID=11111
USERNAME=username
PASSWORD=password
API_PATH="remote.php/dav/trash-bin/$USERNAME/$FILE_ID"
SERVER_URI="https://owncloud.install.com/owncloud"
curl "$SERVER_URI/$API_PATH/" \
-H 'Overwrite: F' \
-H 'Destination: $SERVER_URI/remote.php/dav/files/$USERNAME/<filepath>' \
-X MOVE \
--user "$USERNAME:$PASSWORD"
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:
<?xml version="1.0" encoding="utf-8"?>
<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
<s:exception>Sabre\DAV\Exception\PreconditionFailed</s:exception>
<s:message>The destination node already exists, and the overwrite header is set to false</s:message>
<s:header>Overwrite</s:header>
</d:error>
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:
<?xml version="1.0" encoding="utf-8"?>
<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
<s:exception>Sabre\DAV\Exception\BadRequest</s:exception>
<s:message>The HTTP Overwrite header should be either T or F</s:message>
</d:error>
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:
<?xml version="1.0" encoding="utf-8"?>
<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
<s:exception>Sabre\DAV\Exception\Conflict</s:exception>
<s:message>The destination node is not found</s:message>
</d:error>