comment-tree resource endpoint

URL: /assets/<id>/comment-tree.<format>

This endpoint is an alternate representation of the data returned by the /assets/<id>/comments endpoint which is intended to be more amenable to rendering a conversation in a threaded format rather than a flat format.

The first difference is that the comments are returned in an order which places the replies to a particular comment directly after it in the list, rather than ordering all of the comments chronologically. Within each level of the comment heirarchy the comments are still returned in chronological order. The second difference is that rather than being returned directly each comment is returned wrapped in a CommentTreeItem object which allows a client to determine the nesting depth of the comment.

The most straightforward way to process and render this data is to use the depth parameter as a multiplier for a visual indent size while still treating the result as a flat list. This will achieve a tree-like presentation visually, although this approach does not translate well for non-visual media.

A client can also use the guarantee made about the ordering of the response items to determine the real tree structure based on changes in depth. However, clients doing this must take care to react appropriately when pagination causes the first item returned to have a depth of two or more, indicating that it is actually a reply to a comment on the previous page rather than a comment on the root item.





Supported Methods

GET Get a list of assets that were posted in response to the selected asset and their depth in the response tree

Query String Arguments

start-index
Index of the first item to return. The first item in the list has index 1.
max-results
Maximum number of items to return in the list response.
selected-item
The urlId of an item that must be included in the response. The response will be an even page of results containing the selected item.

Resource Type

This endpoint returns an object of type List<CommentTreeItem>.

entries (array<CommentTreeItem>)
The items within the selected range.
totalResults (integer)
The total number of items in the whole list of which this object is a chunk.

Client Library Methods for PHP

Get a list of assets that were posted in response to the selected asset and their depth in the response tree
$tp->assets->getCommentTree(array(

    # Required Parameters
    "id" => $id,

    # Optional Parameters
    "limit" => $limit,
    "offset" => $offset,
    "selectedItem" => $selectedItem,

))

Example Request

GET /assets/6a012877b13de7970c012877b143d0970c/comment-tree.json?max-results=4 HTTP/1.1
Host: api.typepad.com

HTTP/1.0 200 OK
Content-type: application/json
Content-length: 12167

{
   "entries": [
      {
         "comment": {
            "content": "Hi Bob! What kind of law do you practice?",
            "favoriteCount": 0,
            "author": {
               "urlId": "6p0120a8ae8949970b",
               "location": null,
               "interests": [],
               "objectTypes": [
                  "tag:api.typepad.com,2009:User"
               ],
               "profilePageUrl": "http://profile.typepad.com/matkinsdevin",
               "aboutMe": null,
               "objectType": "User",
               "preferredUsername": "matkinsdevin",
               "id": "tag:api.typepad.com,2009:6p0120a8ae8949970b",
               "avatarLink": {
                  "width": 250,
                  "urlTemplate": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/08-{spec}.gif",
                  "url": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/08-250si.gif",
                  "height": 250
               },
               "displayName": "Devin Jineer"
            },
            "objectType": "Comment",
            "groups": [],
            "root": {
               "urlId": "6a012877b13de7970c012877b143d0970c",
               "excerpt": "I've started this blog to share interesting law facts and information about cases I find interesting. Information in this blog is not legal advice.",
               "objectTypes": [
                  "tag:api.typepad.com,2009:Post"
               ],
               "author": {
                  "urlId": "6p012877b13de7970c",
                  "location": null,
                  "interests": [],
                  "objectTypes": [
                     "tag:api.typepad.com,2009:User"
                  ],
                  "profilePageUrl": "http://profile.typepad.com/loblawatlaw",
                  "aboutMe": null,
                  "objectType": "User",
                  "preferredUsername": "loblawatlaw",
                  "id": "tag:api.typepad.com,2009:6p012877b13de7970c",
                  "avatarLink": {
                     "width": 250,
                     "urlTemplate": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-{spec}.gif",
                     "url": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-250si.gif",
                     "height": 250
                  },
                  "displayName": "Bob Loblaw"
               },
               "permalinkUrl": "http://bobloblaw.typepad.com/blog/2010/02/welcome-t.html",
               "href": "assets/6a012877b13de7970c012877b143d0970c.json",
               "objectType": "Post",
               "type": "application/json",
               "id": "tag:api.typepad.com,2009:6a012877b13de7970c012877b143d0970c",
               "title": "Welcome to my Blog"
            },
            "id": "tag:api.typepad.com,2009:6a012877b13de7970c012877b15d80970c",
            "urlId": "6a012877b13de7970c012877b15d80970c",
            "inReplyTo": {
               "urlId": "6a012877b13de7970c012877b143d0970c",
               "excerpt": "I've started this blog to share interesting law facts and information about cases I find interesting. Information in this blog is not legal advice.",
               "objectTypes": [
                  "tag:api.typepad.com,2009:Post"
               ],
               "author": {
                  "urlId": "6p012877b13de7970c",
                  "location": null,
                  "interests": [],
                  "objectTypes": [
                     "tag:api.typepad.com,2009:User"
                  ],
                  "profilePageUrl": "http://profile.typepad.com/loblawatlaw",
                  "aboutMe": null,
                  "objectType": "User",
                  "preferredUsername": "loblawatlaw",
                  "id": "tag:api.typepad.com,2009:6p012877b13de7970c",
                  "avatarLink": {
                     "width": 250,
                     "urlTemplate": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-{spec}.gif",
                     "url": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-250si.gif",
                     "height": 250
                  },
                  "displayName": "Bob Loblaw"
               },
               "permalinkUrl": "http://bobloblaw.typepad.com/blog/2010/02/welcome-t.html",
               "href": "assets/6a012877b13de7970c012877b143d0970c.json",
               "objectType": "Post",
               "type": "application/json",
               "id": "tag:api.typepad.com,2009:6a012877b13de7970c012877b143d0970c",
               "title": "Welcome to my Blog"
            },
            "objectTypes": [
               "tag:api.typepad.com,2009:Comment"
            ],
            "container": {
               "urlId": "6a012877b13de7970c012877b13df1970c",
               "objectType": "Blog",
               "id": "tag:api.typepad.com,2009:6a012877b13de7970c012877b13df1970c",
               "homeUrl": "http://bobloblaw.typepad.com/blog/",
               "displayName": "Bob Loblaw Law Blog"
            },
            "description": null,
            "commentCount": 0,
            "published": "2010-02-18T00:35:48Z",
            "permalinkUrl": "http://bobloblaw.typepad.com/blog/2010/02/welcome-t.html?cid=6a012877b13de7970c012877b15d80970c#comment-6a012877b13de7970c012877b15d80970c",
            "textFormat": "html_convert_linebreaks",
            "commenter": {
               "href": "http://devindev.typepad.com/",
               "name": "Devin Jineer",
               "avatarLink": {
                  "width": 250,
                  "urlTemplate": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/08-{spec}.gif",
                  "url": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/08-250si.gif",
                  "height": 250
               }
            },
            "title": null
         },
         "depth": 1
      },
      {
         "comment": {
            "content": "Hey Devin...\nMy main interest is intellectual property law. Do you share an interest?",
            "favoriteCount": 0,
            "author": {
               "urlId": "6p012877b13de7970c",
               "location": null,
               "interests": [],
               "objectTypes": [
                  "tag:api.typepad.com,2009:User"
               ],
               "profilePageUrl": "http://profile.typepad.com/loblawatlaw",
               "aboutMe": null,
               "objectType": "User",
               "preferredUsername": "loblawatlaw",
               "id": "tag:api.typepad.com,2009:6p012877b13de7970c",
               "avatarLink": {
                  "width": 250,
                  "urlTemplate": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-{spec}.gif",
                  "url": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-250si.gif",
                  "height": 250
               },
               "displayName": "Bob Loblaw"
            },
            "objectType": "Comment",
            "groups": [],
            "root": {
               "urlId": "6a012877b13de7970c012877b143d0970c",
               "excerpt": "I've started this blog to share interesting law facts and information about cases I find interesting. Information in this blog is not legal advice.",
               "objectTypes": [
                  "tag:api.typepad.com,2009:Post"
               ],
               "author": {
                  "urlId": "6p012877b13de7970c",
                  "location": null,
                  "interests": [],
                  "objectTypes": [
                     "tag:api.typepad.com,2009:User"
                  ],
                  "profilePageUrl": "http://profile.typepad.com/loblawatlaw",
                  "aboutMe": null,
                  "objectType": "User",
                  "preferredUsername": "loblawatlaw",
                  "id": "tag:api.typepad.com,2009:6p012877b13de7970c",
                  "avatarLink": {
                     "width": 250,
                     "urlTemplate": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-{spec}.gif",
                     "url": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-250si.gif",
                     "height": 250
                  },
                  "displayName": "Bob Loblaw"
               },
               "permalinkUrl": "http://bobloblaw.typepad.com/blog/2010/02/welcome-t.html",
               "href": "assets/6a012877b13de7970c012877b143d0970c.json",
               "objectType": "Post",
               "type": "application/json",
               "id": "tag:api.typepad.com,2009:6a012877b13de7970c012877b143d0970c",
               "title": "Welcome to my Blog"
            },
            "id": "tag:api.typepad.com,2009:6a012877b13de7970c012877b163d7970c",
            "urlId": "6a012877b13de7970c012877b163d7970c",
            "inReplyTo": {
               "urlId": "6a012877b13de7970c012877b15d80970c",
               "permalinkUrl": "http://bobloblaw.typepad.com/blog/2010/02/welcome-t.html?cid=6a012877b13de7970c012877b15d80970c#comment-6a012877b13de7970c012877b15d80970c",
               "objectType": "Comment",
               "href": "assets/6a012877b13de7970c012877b15d80970c.json",
               "objectTypes": [
                  "tag:api.typepad.com,2009:Comment"
               ],
               "type": "application/json",
               "id": "tag:api.typepad.com,2009:6a012877b13de7970c012877b15d80970c",
               "author": {
                  "urlId": "6p0120a8ae8949970b",
                  "location": null,
                  "interests": [],
                  "objectTypes": [
                     "tag:api.typepad.com,2009:User"
                  ],
                  "profilePageUrl": "http://profile.typepad.com/matkinsdevin",
                  "aboutMe": null,
                  "objectType": "User",
                  "preferredUsername": "matkinsdevin",
                  "id": "tag:api.typepad.com,2009:6p0120a8ae8949970b",
                  "avatarLink": {
                     "width": 250,
                     "urlTemplate": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/08-{spec}.gif",
                     "url": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/08-250si.gif",
                     "height": 250
                  },
                  "displayName": "Devin Jineer"
               }
            },
            "objectTypes": [
               "tag:api.typepad.com,2009:Comment"
            ],
            "container": {
               "urlId": "6a012877b13de7970c012877b13df1970c",
               "objectType": "Blog",
               "id": "tag:api.typepad.com,2009:6a012877b13de7970c012877b13df1970c",
               "homeUrl": "http://bobloblaw.typepad.com/blog/",
               "displayName": "Bob Loblaw Law Blog"
            },
            "description": null,
            "commentCount": 0,
            "published": "2010-02-18T00:43:34Z",
            "permalinkUrl": "http://bobloblaw.typepad.com/blog/2010/02/welcome-t.html?cid=6a012877b13de7970c012877b163d7970c#comment-6a012877b13de7970c012877b163d7970c",
            "textFormat": "html_convert_linebreaks",
            "commenter": {
               "href": "http://bobloblaw.typepad.com/",
               "name": "Bob Loblaw",
               "avatarLink": {
                  "width": 250,
                  "urlTemplate": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-{spec}.gif",
                  "url": "http://static.typepad.com/.shared:v03b8f01:typepad:en_us/default-userpics/11-250si.gif",
                  "height": 250
               }
            },
            "title": null
         },
         "depth": 2
      }
   ],
   "totalResults": 2
}