In the last post we took a look at associations, this time we're going to cover some of the collaboration APIs that have been present for a few releases, namely comments, ratings and tags.
As usual this post is accompanied by a Postman collection, click the "Run in Postman" button below to import it into your client.
We'll need some content to use throughout this post, either refer back to part 3, execute the first request in the Postman collection or POST the following body to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children to create a node:
{
"name": "collaboration.txt",
"nodeType": "cm:content"
}Let's start by creating a comment on our content (2nd request in the Postman collection), POST the body below to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/comments:
{
"content": "This is my comment"
}This will result in a response similar to the one below:
{
"entry": {
"createdAt": "2016-12-13T18:15:30.450+0000",
"createdBy": {
"firstName": "Test",
"lastName": "Test",
"emailNotificationsEnabled": true,
"company": {
},
"id": "test",
"enabled": true,
"email": "test@alfresco.com"
},
"edited": false,
"modifiedAt": "2016-12-13T18:15:30.450+0000",
"canEdit": true,
"modifiedBy": {
"firstName": "Test",
"lastName": "Test",
"emailNotificationsEnabled": true,
"company": {
},
"id": "test",
"enabled": true,
"email": "test@alfresco.com"
},
"canDelete": true,
"id": "42fbc51b-3e9a-4237-ad23-bfd8c6bcbc6a",
"content": "This is my comment"
}
}Take a copy of the newly created id as we'll need it shortly, hereinafter referred to as "fileId".
To retrieve all the comments on a node we use http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/comments (3rd request in the Postman collection), at the moment our node only has the one comment:
{
"list": {
"pagination": {
"count": 1,
"hasMoreItems": false,
"totalItems": 1,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"createdAt": "2016-12-13T18:15:30.450+0000",
"createdBy": {
"firstName": "Test",
"lastName": "Test",
"emailNotificationsEnabled": true,
"company": {
},
"id": "test",
"enabled": true,
"email": "test@alfresco.com"
},
"edited": false,
"modifiedAt": "2016-12-13T18:15:30.450+0000",
"canEdit": true,
"modifiedBy": {
"firstName": "Test",
"lastName": "Test",
"emailNotificationsEnabled": true,
"company": {
},
"id": "test",
"enabled": true,
"email": "test@alfresco.com"
},
"canDelete": true,
"id": "42fbc51b-3e9a-4237-ad23-bfd8c6bcbc6a",
"content": "This is my comment"
}
}
]
}
}Each comment has a canEdit (line 27) and canDelete (line 39) property, this can be used to determine whether the current user has the permission to edit or delete that comment, respectively.
What if we made a typo in our comment and we need to update it, we can achieve that by using PUT with a Content-Type of application/json to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/comments/{{... (4th request in the Postman collection). Send the following body to update the content text to "Updated comment".
{
"content": "Updated comment"
}Presuming we have permission to delete a comment we can do so by sending a DELETE request to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/comments/{{... (5th request in the Postman collection).
Now let's take a look at "liking" a node. To do this we use the ratings API, likes is one of the rating schemes available out-of-the-box, fiveStar is the other, although this is not currently used by any Alfresco client. An explanation of rating schemes is beyond the scope of this article so I'll that as an exercise for the reader.
To "like" a node we can POST the body below to: http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/ratings (6th request in the Postman collection). The value required for the myRating property depends on the rating scheme, for likes it's a boolean flag.
{
"id": "likes",
"myRating": true
}This will result in the following response. It shows our rating (line 3), the rating type we applied (line 5) and the number of times this node has been rated (line 7) with that particular scheme.
{
"entry": {
"myRating": true,
"ratedAt": "2016-12-13T19:28:23.792+0000",
"id": "likes",
"aggregate": {
"numberOfRatings": 1
}
}
}If we retrieve the ratings for the node using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/ratings (7th request in the Postman collection) we'll see an entry for each rating scheme installed in the repository. If you've rated the node with one of the schemes the myRating property will be present (line 21). Each scheme also shows the total number of ratings applied (lines 15 and 25).
{
"list": {
"pagination": {
"count": 2,
"hasMoreItems": false,
"totalItems": 2,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"id": "fiveStar",
"aggregate": {
"numberOfRatings": 0
}
}
},
{
"entry": {
"myRating": true,
"ratedAt": "2016-12-13T19:28:23.792+0000",
"id": "likes",
"aggregate": {
"numberOfRatings": 1
}
}
}
]
}
}If you rate the node again using another user and retrieve the ratings again you'll notice the numberOfRatings property on line 25 change to 2.
So what if we change our mind and decide that we no longer "like" the node, how do we "unlike" it? To do this we DELETE the rating scheme from the node using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/ratings/lik... (8th request in the Postman collection). This doesn't remove the whole rating scheme, it just removes our rating from the node.
If we retrieve just the likes ratings for the node using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/ratings/lik... (9th request in the Postman collection) you'll notice the myRating property has been removed and the numberOfRatings count has decreased as shown below:
{
"entry": {
"id": "likes",
"aggregate": {
"numberOfRatings": 0
}
}
}Let's now turn our attention to tags. To add a tag to a node we simply POST the body shown below to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/tags (10th request in the Postman collection😞
{
"tag": "blog"
}This results in the following response:
{
"entry": {
"tag": "blog",
"id": "ecbe5049-a879-4b96-8c25-c8a776e43464"
}
}Add another tag called "post" to the same node (11th request in the Postman collection). We can then retrieve the tags applied to the node by using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/tags (12th request in the Postman collection), you should see a response similar to the one below:
{
"list": {
"pagination": {
"count": 2,
"hasMoreItems": false,
"totalItems": 2,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"tag": "blog",
"id": "2c1be151-bbae-418a-9ddc-541a6a867c94"
}
},
{
"entry": {
"tag": "post",
"id": "9e41ee8b-fdac-4cbd-bde1-082b486ccc7c"
}
}
]
}
}When we add a tag to a node we're actually creating a global tag in the repository which we can see by retrieving all tags using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/tags (13th request in the Postman collection). If you look closely at the response you'll notice the id of the tags are the same as the ones returned for the node above.
{
"list": {
"pagination": {
"count": 2,
"hasMoreItems": false,
"skipCount": 0,
"maxItems": 100
},
"entries": [
{
"entry": {
"tag": "blog",
"id": "2c1be151-bbae-418a-9ddc-541a6a867c94"
}
},
{
"entry": {
"tag": "post",
"id": "9e41ee8b-fdac-4cbd-bde1-082b486ccc7c"
}
}
]
}
}As tags are global to the repository removing them from a node does not delete the tag itself, let's see this in action by removing the "blog" tag from our node. To do this we need to DELETE using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/{{fileId}}/tags/{{tagI... (14th request in the Postman collection) where tagId is "2c1be151-bbae-418a-9ddc-541a6a867c94".
Following a successful 204 response retrieve the tags for the node and the repository (12th and 13th requests in the Postman collection) and you'll see the "blog" tag has gone from the node but is still in the repository and available for use on other nodes.
Those of you paying close attention would have noticed that we only supplied the text of the tag when we added it to our node earlier. Before creating a new tag the API will first look for a matching existing tag and use that if it's present, meaning clients do not have to keep track of the underlying id of the tag.
That concludes our overview of the collaboration APIs for nodes, in the next post we'll look at the collaboration APIs for sites.
