Working with the trash

When documents or folders are deleted they are sent to the Trash. Items in the trash can be listed, purged, or restored.

There are two levels of Trash:

  1. User: items the user has deleted from their personal library, a corporate library, or another user's personal library
  2. Deployment: items deleted from corporate libraries

For example, if a user deletes an item from a corporate library, that item will be listed in both the user's trash and the deployment's trash. If a user deletes an item from their personal library, that item will only be listed in their user trash. A user can purge or restore any items in the trash that they have access to, but only users with a site admin role can interact with the Deployment Trash.

Retrieving trash for the current user

To retrieve the list of items you have deleted, issue the following GET request:

GET /api/trash

This will return a response body like the following:

[
    {
        "ItemName": "project.docx",
        "ItemType": "document",
        "DateDeleted": "2017-11-30T20:06:54.32Z",
        "DeletedByUserName": "Sam User",
        "Embedded": {
            "Document": {
                "DocumentId": 10,
                "DocumentName": "project.docx",
                "DateModified": "2017-11-30T20:06:47.25Z",
                "Links": {...},
            },
            "Folder": null,
            "Library": {...}
        }
        "Links": {
            "RestoreUri": "https://app.sharebase.com/sharebaseapi/api/documents/10/restore"
        }
    },
    {
        "ItemName": "My Documents",
        "ItemType": "folder",
        "DateDeleted": "2017-11-30T15:07:05.417",
        "DeletedByUserName": "Sam User",
        "Embedded": {
            "Document": null,
            "Folder": {
                "FolderId": 1,
                "FolderName": "My Documents",
                "Links": {...},
                "Embedded": {
                    "Folders": [],
                    "Documents": []
                }
            },
            "Library": {
                "LibraryId": 1,
                "LibraryName": "My Library",
                "IsPrivate": true,
                "Links": {...}
            }
        }
        "Links": {
            "RestoreUri": "https://app.sharebase.com/sharebaseapi/api/folders/1/restore"
        }
    }
]

Where:

  • ItemName: the name of the deleted item
  • ItemType: what type of item it was (e.g. document, folder, library)
  • DateDeleted: the timestamp of when the item was deleted
  • DeletedByUserName: who deleted the item
  • Embedded: is an object representing the deleted item
  • Document: a document object representing the item, NULL if it wasn't a document
  • Folder: a folder object representing the item, NULL if it wasn't a folder
  • Library: a library object representing the Library the item was in
  • Links: a list of links related to the deleted item
  • RestoreUri: is a URI to restore item. This is explained in more detail here

Retrieving trash for deployment libraries

This requires Site Admin privileges to access

To retrieve the list of items that users have deleted from corporate libraries or folders, issue the following GET request:

GET /api/admin/trash

This will return a response body like the following:

[
    {
        "ItemName": "README.md",
        "ItemType": "document",
        "DateDeleted": "2017-11-30T16:47:16.623",
        "DeletedByUserName": "Sam User",
        "Embedded": {
            "Document": {
                "DocumentId": 11,
                "DocumentName": "README.md",
                "DateModified": "2017-11-30T21:47:12.227Z",
                "Hash": "tZP9B9XighS8qJQG8wAzU0fEJUw=",
                "Links": {
                    "Self": "https://app.sharebase.com/sharebaseapi/api/documents/11",
                    "Content": "https://app.sharebase.com/sharebaseapi/api/documents/11/content"
                }
            },
            "Folder": null,
            "Library": {
                "LibraryId": 2,
                "LibraryName": "ShareBase Public API",
                "IsPrivate": false,
                "Links": {
                    "Self": "https://app.sharebase.com/sharebaseapi/api/libraries/2",
                    "Folders": "https://app.sharebase.com/sharebaseapi/api/libraries/2/folders"
                }
            }
        }
        "Links": {
            "RestoreUri": "https://app.sharebase.com/sharebaseapi/api/documents/11/restore"
        }
    },
]

Restoring trash

Both trash endpoints return objects that contain a RestoreUri link. You can use this link to restore items from the trash into the folder they were deleted from:

PATCH /api/documents/{documentId}/restore

PATCH /api/folders/{folderId}/restore

Where:

  • documentId: the ID of the document to restore
  • folderId: the ID of the folder to restore

Alternatively, you can pass in a different folder ID to the endpoint and restore the item to that folder:

PATCH /api/documents/{documentId}/restore?into={destination-folderId}

PATCH /api/folders/{id}/restore?into={destination-folderId}

Where:

  • documentId: the ID of the document to restore
  • folderId: the ID of the folder to restore
  • destination folderId: the ID of the folder to restore into

Deleting a document

To delete a document, issue the following DELETE request:

DELETE /api/documents/{documentId}

Where:

  • documentId: the ID of the document to delete

Alternatively, you can issue a DELETE on document.Links.Self.

Deleting a folder

To delete a folder, issue the following DELETE request:

DELETE /api/folders/{folderId}

Where:

  • folderId: the ID of the folder to delete

Alternatively, you can issue a DELETE on folder.Links.Self.

Purging a folder

To permanently delete a folder, issue the following DELETE request:

DELETE /api/folders/{folderId}?purge=true

Where:

  • folderId: the ID of the folder to delete

Purging a folder will make it unrecoverable.

  • If the "Enable Purging" deployment setting is deselected, this request will return with an HTTP 403 Forbidden error response.

Purging a document

To permanently delete a document issue the following DELETE request:

DELETE /api/documents/{documentId}?purge=true

Where:

  • documentId: the ID of the document to delete

Purging a document will make it unrecoverable.

  • If the "Enable Purging" deployment setting is deselected, this request will return with an HTTP 403 Forbidden error response.

Purging old documents

To permanently delete all documents as old or older than a specified number days, issue the following POST request:

POST /api/async/documents/purge-old-documents

With the following body: 

{
    "PurgeType":"DateStored",
    "Days":90
}

  • PurgeType: The type of purge to perform. This specifies how document age is determined and must be a valid value:

    • DateStored: This purge type specifies that the age of a document is based on the date it was stored.

  • Days: The minimum number of days old a document must be for it to be purged. Anything that old or older will be purged. Minimum number of days is 60.

Warning

WARNING: This endpoint purges old documents for ALL USERS from all personal and corporate libraries, and can be run only by a Site Admin.

  • If the job is added to the async queue successfully, an HTTP 202 OK status code is returned.
  • If the PurgeType or Days parameters are invalid, an HTTP 400 Bad Request is returned.
  • If the user is not a Site Admin, or if the "Enable Purging" deployment setting is deselected, then an HTTP 403 Forbidden response is returned.

Retrieving results from purging old documents

To retrieve the output from the purge-old-documents async operation, issue the following GET request:

POST /api/async/results/documents/purge-old-documents/{id}

Where:

  • id: the id of the async job.

If the retrieval was successful, an HTTP 200 OK status code is returned with the following response body: 

{
    "DocumentsDeleted": 72,
    "DocumentsThatFailedToDelete": 0
}
  • DocumentsDeleted: The number of documents that were successfully purged (deleted permanently) from the system.
  • DocumentsThatFailedToDelete: The number of documents that encountered a problem during deletion and failed to delete.

NOTE: The job will be cleaned up once it has been retrieved, and the results will no longer be available.

  • If the job has not been completed yet, an HTTP 303 See Other response is returned.
  • If the user is not a Site Admin, then an HTTP 403 No Access response is returned.
  • If the async job with the requested job id cannot be found, then an HTTP 410 Gone response is returned.