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

username

string

The username of the user to list files for.

Request Headers

Header Type Description

Depth

int

The maximum level to descend to, when retrieving a listing of the files in the user’s trash bin.

Only one level of files and directories is returned if this header is omitted.

Code Example

  • Curl

#!/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:

  • Curl

<?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

Permanently delete a file from the trash bin.

  • Path: remote.php/dav/trash-bin/<username>/<fileid>

  • Method: DELETE

Request Parameters

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

  • Curl

#!/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/" \
    -X DELETE \
    --user "$USERNAME:$PASSWORD"

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: remote.php/dav/trash-bin/<username>/<fileid>

  • Method: MOVE

Request Parameters

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

Header Type Value Description

Overwrite

string

F or T

Whether to overwrite an existing file.

Destination

string

/remote.php/dav/files/<username>/<filepath>

The path where the file will be restored to.

Code Example

  • Curl

#!/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>