gavincornwell

v1 REST API - Part 11 - Trashcan

Blog Post created by gavincornwell Employee on Apr 24, 2017

In the last post we discussed the people API, this time I'm going to show you how you can manage deleted nodes via the trashcan API.

 

As usual, there is a Postman collection to go with this post, click the "Run in Postman" button below to import it into your client.

 

 

Before we can start looking at the trashcan API we need to do a little bit of setup by deleting a node. Firstly, make sure your repository has the test user we created back in part 8. The 1st and 2nd request of the Postman collection creates and deletes a file, respectively. 

 

To list the nodes that have been deleted we can use http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/deleted-nodes (3rd request in the Postman collection), the response will look similar to the one below:

{
  "list": {
    "pagination": {
      "count": 1,
      "hasMoreItems": false,
      "totalItems": 1,
      "skipCount": 0,
      "maxItems": 100
    },
    "entries": [
      {
        "entry": {
          "createdAt": "2017-04-11T13:53:02.359+0000",
          "archivedAt": "2017-04-11T13:55:56.432+0000",
          "isFolder": false,
          "isFile": true,
          "createdByUser": {
            "id": "test",
            "displayName": "Test User"
          },
          "modifiedAt": "2017-04-11T13:53:02.359+0000",
          "modifiedByUser": {
            "id": "test",
            "displayName": "Test User"
          },
          "name": "content-to-be-deleted.txt",
          "archivedByUser": {
            "id": "test",
            "displayName": "Test User"
          },
          "id": "1860a21b-b6d2-4cde-aadd-e0bd521787cf",
          "nodeType": "cm:content",
          "content": {
            "mimeType": "text/plain",
            "mimeTypeName": "Plain Text",
            "sizeInBytes": 0,
            "encoding": "UTF-8"
          }
        }
      }
    ]
  }
}

 

The response should look familiar, it's based on the response of /nodes/{{nodeId}}/children with a couple of additions. There is an additional archivedAt property and an archivedByUser property providing details of when the node was archived and by whom. By default, the list is ordered by the archivedAt property, with the most recently deleted being first in the list.

 

As with the nodes API some information is omitted for performance reasons, see the API Explorer for the additional information you can request via the include query parameter.

 

Calling this endpoint as a normal user will only return the nodes you have deleted, however, if you are an administrator, all deleted nodes in the system are returned.

 

To get details of an individual deleted node http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/deleted-nodes/{{nodeId}} (4th request in the Postman collection) can be used. This endpoint returns a little more information about the deleted node (see below) by default but again there is some optional information that can be added via the include query parameter, see the API Explorer for details.

{
  "entry": {
    "isFile": true,
    "createdByUser": {
      "id": "test",
      "displayName": "Test User"
    },
    "modifiedAt": "2017-04-11T13:53:02.359+0000",
    "nodeType": "cm:content",
    "content": {
      "mimeType": "text/plain",
      "mimeTypeName": "Plain Text",
      "sizeInBytes": 0,
      "encoding": "UTF-8"
    },
    "aspectNames": [
      "rn:renditioned",
      "cm:ownable",
      "cm:auditable",
      "cm:thumbnailModification"
    ],
    "createdAt": "2017-04-11T13:53:02.359+0000",
    "archivedAt": "2017-04-11T13:55:56.432+0000",
    "isFolder": false,
    "modifiedByUser": {
      "id": "test",
      "displayName": "Test User"
    },
    "name": "content-to-be-deleted.txt",
    "archivedByUser": {
      "id": "test",
      "displayName": "Test User"
    },
    "id": "1860a21b-b6d2-4cde-aadd-e0bd521787cf",
    "properties": {
      "cm:lastThumbnailModification": [
        "doclib:1491918788304"
      ],
      "cm:owner": {
        "id": "test",
        "displayName": "Test User"
      }
    }
  }
}

 

As you would expect, the API also allows you to restore a deleted node which removes it from the list of deleted nodes and puts it back in the "live" store. You can do this by POSTing to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/deleted-nodes/{{nodeId}}/restore (5th request in the Postman collection). For this endpoint there is no body to send. If the node was successfully restored you will receive a 200 OK response with a representation of the "live" node.  

 

Just to make sure you can list the deleted nodes again using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/deleted-nodes (3rd request in the Postman collection) and you should see an empty list as shown below:

{
  "list": {
    "pagination": {
      "count": 0,
      "hasMoreItems": false,
      "totalItems": 0,
      "skipCount": 0,
      "maxItems": 100
    },
    "entries": []
  }
}

 

The opposite or restoring a node is to permanently delete it, once this is done it's final, there is no way to get the node back! To try this out we need to repeat the setup process so re-run the 1st and 2nd request in the Postman collection.

 

To permanently delete a node send a DELETE request to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/deleted-nodes/{{nodeId}} (6th request in the Postman collection), if the deletion was successful you will receive an empty response with a 204 status code.

 

List the deleted nodes (3rd request in the Postman collection) and you will see an empty list once again.

 

If you want to bypass the trashcan completely you can permanently delete a "live" node by using the permanent query parameter, see the API Explorer for details.

 

Hopefully that's given you a good overview of the trashcan API and what's possible, next time we're going to look at the only remaining API we haven't covered yet, the discovery API.

Outcomes