Navigation

API Documentation

Comments

Goal

In an earlier chapter (Content Objects), we created some content that we are going to use in this chapter:

  • an article
    • title: 'My Last Trip to Rome'
    • UUID: 11111111-1111-1111-1111-111111111111
  • a review
    • title: 'Villa Medici - The Guided Tour'
    • UUID: 44444444-4444-4444-4444-444444444444

Let's say that some website visitors have already left a few comments for the review (You can see the tree structure for those comments below).

Now we want to add some more website visitor interaction by adding comments to the article as well. We're going to add:

  • one (top-level) comment that is directly associated with the article, and
  • one (sub-level) comment that is a reply to the comment above.

But first, a short introduction to the Metro Publisher commenting system:

Comments in Metro Publisher

Note

Currently, commenting is only available for content objects (see content types).

Comments may either be top-level comments, i.e. they are directly made/connected to a content object, or they may be a sub-level comment, i.e. they are a reply to another comment. This means that comments may have a tree-structure:

  • Content A
    • Comment 1
      • Comment 1-1 (Reply to 1)
        • Comment 1-1-1 (Reply to 1-1)
    • Comment 2
      • Comment 2-1 (Reply to 2)
    • Comment 3

Every Metro Publisher instance has two settings options regarding comments:

  • Auto Approve Comments
  • Require Email for Comments

These two options will not be enforced when creating comments via the API, i.e. you may add a comment via the API without an email address even if the 'Require Email for Comments' switch is enabled in the respective Metro Publisher instance.

Adding Comments

In order to create a comment for the article 'My Last Trip to Rome', we send a PUT request to the /{iid}/comments/{uuid} resource like this:

>>> PUT("/123/comments/11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
... {"title": "I think...",
...  "comment": "... this article rocks!",
...  "creator": "Hans Meier",
...  "created": "2012-08-12T10:10:00",
...  "fb_uid": 12345678910,
...  "email": "hans.meier@domain.com",
...  "state": "published",
...  "parent_type": "content",
...  "parent_uuid": "11111111-1111-1111-1111-111111111111"})
{'url': 'https://api.metropublisher.com/123/comments/11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
 'uuid': '11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa'}

The parameters parent_type and parent_uuid specify which object the comment is associated with. In this case it means that this is a comment for a content object with the UUID '11111111-1111-1111-1111-111111111111', which is the article 'My Last Trip to Rome'.

The parameters fb_uid (Facebook User ID) and email are optional and refer to the person who authored the comment.

Replying to a Comment

When creating a reply to a comment, we also send a PUT request to the /{iid}/comments/{uuid} resource:

>>> PUT("/123/comments/11111111-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
... {"title": "I agree",
...  "comment": "You're right, this article rocks!",
...  "creator": "Peter Smith",
...  "created": "2012-08-12T12:00:00",
...  "fb_uid": 1234512345,
...  "email": "p.smith@mydomain.com",
...  "state": "published",
...  "parent_type": "comment",
...  "parent_uuid": "11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa"})
{'url': 'https://api.metropublisher.com/123/comments/11111111-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
 'uuid': '11111111-bbbb-bbbb-bbbb-bbbbbbbbbbbb'}

This time, however, the parent_type is comment and the parent_uuid is the UUID of the (here: top-level) comment we created in the section above ('11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa').

A reply to a reply is created similarly: parent_type is 'comment' and parent_uuid is the UUID of the "parent" reply.

Retrieving Comments

Now there are five comments (two top-level, three sub-level comments) for the review and two comments (one top-level with one reply) for the article (see tree below). With the GET/{iid}/comments resource we can get a list of those comments and replies.

As with the other collection resources of the API, GET /{iid}/comments takes several parameters to sort and filter the returned list.

Tree Structure

Besides being able to order the list of comments by title or creation date, the order parameter allows for a special ordering: tree. This will return the list of comments and replies in the order they appear in the tree.

>>> GET("/123/comments?fields=title-url-parent_type-parent_uuid&order=tree")
{'items': [['Another great review',
            'https://api.metropublisher.com/123/comments/44444444-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
            'content',
            '44444444-4444-4444-4444-444444444444'],
           ['Love the villa!',
            'https://api.metropublisher.com/123/comments/44444444-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
            'comment',
            '44444444-aaaa-aaaa-aaaa-aaaaaaaaaaaa'],
           ['Also great in winter',
            'https://api.metropublisher.com/123/comments/44444444-dddd-dddd-dddd-dddddddddddd',
            'comment',
            '44444444-bbbb-bbbb-bbbb-bbbbbbbbbbbb'],
           ['Great author',
            'https://api.metropublisher.com/123/comments/44444444-cccc-cccc-cccc-cccccccccccc',
            'comment',
            '44444444-aaaa-aaaa-aaaa-aaaaaaaaaaaa'],
           ['Always a great place to visit',
            'https://api.metropublisher.com/123/comments/44444444-eeee-eeee-eeee-eeeeeeeeeeee',
            'content',
            '44444444-4444-4444-4444-444444444444'],
           ['I think...',
            'https://api.metropublisher.com/123/comments/11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
            'content',
            '11111111-1111-1111-1111-111111111111'],
           ['I agree',
            'https://api.metropublisher.com/123/comments/11111111-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
            'comment',
            '11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa']]}

The order of this list corresponds to the this tree:

Comments Tree:

|--- 'Another great review' (2012-08-10T10:10:00)                   ⎫
|     |                                                             ⎪
|     |--- 'Love the villa!' (2012-08-10T10:20:00)                  ⎪
|     |     |                                                       ⎪
|     |     |--- 'Also great in winter!' (2012-08-10T10:40:00)      ⎬ review 'Villa Medici - The Guided Tour'
|     |                                                             ⎪
|     |--- 'Great author' (2012-08-10T10:30:00)                     ⎪
|                                                                   ⎪
|--- 'Always a great place to visit' (2012-08-10T10:20:00)          ⎭
|
|--- 'I think...' (2012-08-12T10:10:00)                             ⎫
      |                                                             ⎬ article 'My Last Trip to Rome'
      |--- 'I agree' (2012-08-12T12:00:00)                          ⎭

Note

The tree option cannot be used in conjunction with any other order option.

Filter by Parent

With the parents filter we can retrieve comments for specific content objects, so in order to get all comments for the article 'My Last Trip to Rome', we use the parents parameter:

>>> GET("/123/comments?fields=title-url-parent_type-parent_uuid-parent_url&parents=11111111-1111-1111-1111-111111111111")
{'items': [['I agree',
            'https://api.metropublisher.com/123/comments/11111111-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
            'comment',
            '11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
            'https://api.metropublisher.com/123/comments/11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa'],
           ['I think...',
            'https://api.metropublisher.com/123/comments/11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
            'content',
            '11111111-1111-1111-1111-111111111111',
            'https://api.metropublisher.com/123/content/11111111-1111-1111-1111-111111111111']]}

This list only contains the comments (and their replies) to the article 'My Last Trip to Rome' which has the UUID '11111111-1111-1111-1111-111111111111'.

Retrieving Comment Information

Sending a GET request to /{iid}/comments/{uuid} returns the details for one specific comment (or reply):

>>> GET("https://api.metropublisher.com/123/comments/11111111-bbbb-bbbb-bbbb-bbbbbbbbbbbb")
{'comment': "You're right, this article rocks!",
 'created': '2012-08-12T12:00:00',
 'creator': 'Peter Smith',
 'edited_comment': None,
 'edited_title': None,
 'email': 'p.smith@mydomain.com',
 'fb_uid': '1234512345',
 'parent_type': 'comment',
 'parent_url': 'https://api.metropublisher.com/123/comments/11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
 'state': 'published',
 'title': 'I agree',
 'uuid': '11111111-bbbb-bbbb-bbbb-bbbbbbbbbbbb'}

edited_title and edited_comment

The Metro Publisher administration interface allows some users to edit a comment's title and/or text. If a comment was edited at some point, these edits appear in the fields edited_title and edited_comment.

Table Of Contents

Previous topic

Redirects

Next topic

Content Media

Navigation

© Copyright 2021, Vanguardistas LLC. Created using Sphinx 1.1.3.