3.2 Comments

The examples that follow illustrate how to view, add, edit and delete comments on this file:

{
  "id":"09c1c3fb5256e2e4015256e8691c003b",
  "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-01-18T22:43:37Z"},
  "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2014-04-24T17:05:40Z"},
  "length":14,
  "name":"test.txt",
  "href":"/files/09c1c3fb5256e2e4015256e8691c003b/metadata",
  "links":[...],
  "doc_type":"file",
  "version_number":1,
  "owning_entity":{"id":15,"type":"folderEntry","href":"/folder_entries/15"},
  "parent_binder":{"id":44,"href":"/binders/44"}
}

The owning folder entry (found in the <code>owning_entity</code> property) is the starting point for comments:

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folder_entries/15

[Response]
{
  "id":15,
  "title":"test.txt",
  "href":"/folder_entries/15",
  "doc_type":"entry",
  "entity_type":"folderEntry",
  "entry_type":"entry",  
  "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-01-18T22:43:37Z"},
  "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2016-01-18T22:43:37Z"},
  "parent_binder":{"id":44,"href":"/binders/44"},
  "attachments":[{"id": "09c1c3fb5256e2e4015256e8691c003b",...}],
  "links":[{
    "rel":"replies",
    "href":"/folder_entries/15/replies"
  },{
    "rel":"reply_tree",
    "href":"/folder_entries/15/reply_tree"
  },...],
  "reply_count":2,
  "total_reply_count":3
}

The <code>reply_count</code> property indicates that there are two direct replies to this folder entry. Including replies to those replies, there are 3 replies in all (<code>total_reply_count</code>).

3.2.1 List comments (replies)

To list one level of comments, use the <code>replies</code> related link of the FolderEntry or Reply object.

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folder_entries/15/replies

[Response]
{
  "first":0,
  "count":2,
  "total":2,
  "items":[{
    "id":67,
    "href":"/replies/67",
    "title":"Re: test.txt",
    "description":{
      "text":"Nice work!",
      "format_str":"text"
    },
    "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-29T16:15:41Z"},
    "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-29T16:15:41Z"},
    "links":[
      {"rel":"replies","href":"/replies/67/replies"},
      {"rel":"reply_tree","href":"/replies/67/reply_tree"}
    ],
    "doc_type":"entry",
    "entity_type":"folderEntry",
    "entry_type":"reply",
    "parent_entry":{"id":15,"href":"/folder_entries/15"},
    "top_entry":{"id":15,"href":"/folder_entries/15",
    "parent_binder":{"id":44,"href":"/binders/44"},
    "reply_count":1,
    "total_reply_count":1
  },{
    "id":106,
    "href":"/replies/106",
    "title":"Re: test.txt",
    "description":{
      "text":"I made a few more changes.",
      "format_str":"text"
    },
    "creation":{"principal":{"id":34,"href":"/users/34"},"date":"2016-02-29T16:17:00Z"},
    "modification":{"principal":{"id":34,"href":"/users/34"},"date":"2016-02-29T16:17:00Z"},
    "links":[
      {"rel":"replies","href":"/replies/106/replies"},
      {"rel":"reply_tree","href":"/replies/106/reply_tree"}
    ],
    "doc_type":"entry",
    "entity_type":"folderEntry",
    "entry_type":"reply",
    "parent_binder":{"id":44,"href":"/binders/44"},
    "parent_entry":{"id":15,"href":"/folder_entries/15"},
    "top_entry":{"id":15,"href":"/folder_entries/15"},
    "reply_count":0,
    "total_reply_count":0
  }]
}

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/replies/67/replies

[Response]
{
  "first":0,
  "count":1,
  "total":1,
  "items":[{
    "id":105,
    "href":"/replies/105",
    "title":"Re: Re: test.txt",
    "description":{
      "text":"Thanks.",
      "format_str":"text"
    },
    "creation":{"principal":{"id":34,"href":"/users/34"},"date":"2016-02-29T16:16:53Z"},
    "modification":{"principal":{"id":34,"href":"/users/34"},"date":"2016-02-29T16:16:53Z"},
    "links":[
      {"rel":"replies","href":"/replies/105/replies"},
      {"rel":"reply_tree","href":"/replies/105/reply_tree"}
    ],
    "doc_type":"entry",
    "entity_type":"folderEntry",
    "entry_type":"reply",
    "parent_entry":{"id":67,"href":"/folder_entries/67"},
    "top_entry":{"id":15,"href":"/folder_entries/15",
    "parent_binder":{"id":44,"href":"/binders/44"},
    "reply_count":0,
    "total_reply_count":0
  }]
}

3.2.2 List comment tree (reply_tree)

To get the all comments and their comments in a single request, use the <code>reply_tree</code> related link of the FolderEntry or Reply object:

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folder_entries/15/reply_tree

[Response]
{
  "children":[{
    "item":{
      "id":67,
      "title":"Re: test.txt",
      "description":{"text":"Nice work!","format_str":"text"},
      ...
    },
    "children":[{
      "item":{
        "id":105,
        "title":"Re: Re: test.txt",
        "description":{"text":"Thanks.","format_str":"text"},
        ...
      }
    }]
  },{
    "item":{
      "id":106,
      "title":"Re: test.txt",
      "description":{"text":"I made a few more changes.","format_str":"text"},
      ...
    }
  }]
}

3.2.3 Add comment

To add a comment, POST a Reply object to the "replies" related link of the desired FolderEntry or Reply object. Only the description text is required.

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folder_entries/15/replies \
  -H "Content-Type: application/json" -X POST -d '{"description": {"text":"Great!"}}'

[Response]
{
  "id":107,
  "title":"Re: test.txt",
  "description":{"text":"Great!","format_str":"text"},
  "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-29T22:31:28Z"},
  "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-29T22:31:28Z"},
  "href":"/replies/107",
  "links":[...],
  "parent_binder":{"id":44,"href":"/binders/44"},
  "entry_type":"reply",
  "reply_count":0,
  "total_reply_count":0,
  "parent_entry":{"id":15,"href":"/folder_entries/15"},
  "top_entry":{"id":15,"href":"/folder_entries/15"}
}

3.2.4 Edit comment

To modify a comment, PUT a Reply object to the href of the Reply to update.

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/replies/107 \
  -H "Content-Type: application/json" -X PUT -d '{"description": {"text":"Really great!"}}'

[Response]
{
  "id":107,
  "title":"Re: test.txt",
  "description":{"text":"Really great!","format_str":"text"},
  "creation":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-29T22:31:28Z"},
  "modification":{"principal":{"id":20,"href":"/users/20"},"date":"2016-02-29T22:34:37Z"},
  "href":"/replies/107",
  "links":[...],
  "parent_binder":{"id":44,"href":"/binders/44"},
  "entry_type":"reply",
  "reply_count":0,
  "total_reply_count":0,
  "parent_entry":{"id":15,"href":"/folder_entries/15"},
  "top_entry":{"id":15,"href":"/folder_entries/15"}
}

3.2.5 Delete comment

To delete a comment and all it's child comments, send a DELETE request to the the href of the Reply to update. If the delete is successful, the server responds with an HTTP 204 (No Content) status and an empty response body.

[Request]
> curl -v -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/replies/107 -X DELETE

[Response]
< HTTP/1.1 204 No Content