Comment

A comment is a reader's response to an article in a blog. They appear on the article page in chronological order, typically after the article body.

omni_api_comment_img01

Just as a blog can have any number of articles, an article can have any number of comments. Blog comments are a target for spammers, so haravan's blogs make use of a spam detection system to identify comments that are likely to be spam. Shop owners can mark comments as spam and not spam, which not only hides or unhides them from the readers' view, but also trains the haravan spam detection system.

Authenticated access scopes: com.read_contents, com.write_contents

What you can do with Comment?

The haravan API lets you do the following with the Comment resource. More detailed versions of these general actions may be available:

GET https://apis.haravan.com/web/comments.json?article_id=134645308&blog_id=241253187
- Receive a list of all Comments
GET https://apis.haravan.com/web/comments/count.json?article_id=134645308&blog_id=241253187
- Receive a count of all Comments
GET https://apis.haravan.com/web/comments/{comment_id}.json
- Receive a single Comment
POST https://apis.haravan.com/web/comments.json
- Create a new Comment
PUT https://apis.haravan.com/web/comments/{comment_id}.json
- Modify an existing Comment
POST https://apis.haravan.com/web/comments/{comment_id}/spam.json
- Mark a Comment as spam
POST https://apis.haravan.com/web/comments/{comment_id}/not_spam.json
- Mark a Comment as not spam
POST https://apis.haravan.com/web/comments/{comment_id}/approve.json
- Approve a Comment
POST https://apis.haravan.com/web/comments/{comment_id}/remove.json
- Remove a Comment
POST https://apis.haravan.com/web/comments/{comment_id}/restore.json
- Restore a Comment

Comment Properties

article_id: number

{ "article_id" : 134645308 }

A unique numeric identifier for the article to which the comment belongs.

author: string

{ "author" : "Soleone" }

The name of the author of the comment.

blog_id: number

{ "blog_id" : 241253187  }

A unique numeric identifier for the blog containing the article that the comment belongs to.

body: string

{ "body" : "I really _like_ this." }

The basic textile markup of a comment.

body_html: string

{ "body_html" : "I really _like_ this."}

The text of the comment, complete with HTML markup.

created_at: string

{ "created_at" : "2012-08-24T14:01:46-04:00" }

The date and time when the comment was created. The API returns this value in ISO 8601 format.

email: string

{ "email" : "[email protected]" }

The email address of the author of the comment.

id: number

{ "id" : 653537639 }

A unique numeric identifier for the comment.

ip: string

{ "ip" : "127.0.0.1" }

The IP address from which the comment was posted.

published_at: string

{ "published_at" : "2012-08-24T14:02:00-04:00" }

The date and time when the comment was published. In the case of comments, this is the date and time when the comment was created, meaning that it has the same value as created_at. The API returns this value in ISO 8601 format.

status: string

{ "status" : "removed" }

The status of the comment. The possible values are:

unapproved (default): The comment is awaiting moderation by the shop owner and is not visible to the readers of the blog.
published: The comment has been approved (if the blog requires comments to be moderated) and is visible to readers of the blog.
spam: The comment has been marked as spam by the shop owner and is not visible to readers of the blog.
removed: The comment has been removed from the article.

updated_at: string

{ "updated_at" : "null" }

The date and time when the comment was last modified. When the comment is first created, this is the date and time when the comment was created, meaning that it has the same value as created_at. If the blog requires comments to be approved, this value is updated to the date and time the comment was approved upon approval. The API returns this value in ISO 8601 format.

user_agent: string

{ "user_agent" : "Mozilla/5.0" }

The user agent string provided by the software (usually a browser) used to create the comment.

Endpoints

Receive a list of all Comments

GET

https://apis.haravan.com/web/comments.json

Parameters

limit ≤250 default: 250

Amount of results

page (default: 1)

Page to show

since_id

Restrict results to after the specified ID

created_at_min

Show comments created after date (format: 2008-12-31 03:00)

created_at_max

Show comments created before date (format: 2008-12-31 03:00)

updated_at_min

Show comments last updated after date (format: 2008-12-31 03:00)

updated_at_max

Show comments last updated before date (format: 2008-12-31 03:00)

published_at_min

Show comments published after date (format: 2008-12-31 03:00)

published_at_max

Show comments published before date (format: 2008-12-31 03:00)

fields

comma-separated list of fields to include in the response

published_status

published - Show only published comments
unpublished - Show only unpublished comments
any - Show all comments (default)

status

published - Show only published comments
unapproved - Show only unapproved comments

Get all the comments for a certain article of a blog

GET https://apis.haravan.com/web/comments.json?article_id=134645308&blog_id=241253187

Details

HTTP/1.1 200 OK
{
  "comments": [
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "[email protected]",
      "id": 653537639,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "unapproved",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    },
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "[email protected]",
      "id": 118373535,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "published",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    }
  ]
}

Get all the comments for all the articles of a certain blog

GET https://apis.haravan.com/web/comments.json?blog_id=241253187

Details

HTTP/1.1 200 OK
{
  "comments": [
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "[email protected]",
      "id": 653537639,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "unapproved",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    },
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "[email protected]",
      "id": 118373535,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "published",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    }
  ]
}

Get all the comments for this shop

GET https://apis.haravan.com/web/comments.json

Details

HTTP/1.1 200 OK
{
  "comments": [
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "[email protected]",
      "id": 653537639,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "unapproved",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    },
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "[email protected]",
      "id": 118373535,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "published",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    }
  ]
}

Get all comments after the specified ID

GET https://apis.haravan.com/web/comments.json?since_id=118373535

Details

HTTP/1.1 200 OK
{
  "comments": [
    {
      "article_id": 134645308,
      "author": "Soleone",
      "blog_id": 241253187,
      "body": "Hi author, I really _like_ what you're doing there.",
      "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
      "created_at": "2015-03-28T13:26:28-04:00",
      "email": "[email protected]",
      "id": 653537639,
      "ip": "127.0.0.1",
      "published_at": null,
      "status": "unapproved",
      "updated_at": "2015-03-28T13:26:28-04:00",
      "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
    }
  ]
}

Receive a count of all Comments

GET

https://apis.haravan.com/web/comments/count.json

Get a count of all comments for an article

Parameters

created_at_min

Show comments created after date (format: 2008-12-31 03:00)

created_at_max

Show comments created before date (format: 2008-12-31 03:00)

updated_at_min

Show comments last updated after date (format: 2008-12-31 03:00)

updated_at_max

Show comments last updated before date (format: 2008-12-31 03:00)

published_at_min

Show comments published after date (format: 2008-12-31 03:00)

published_at_max

Show comments published before date (format: 2008-12-31 03:00)

fields

comma-separated list of fields to include in the response

published_status

published - Show only published comments
unpublished - Show only unpublished comments
any - Show all comments (default)

status

pending - All pending comments
published - Show only published comments
unapproved - Show only unapproved comments

Count all comments for a certain article of a blog

GET https://apis.haravan.com/web/comments/count.json?article_id=134645308&blog_id=241253187

Details

HTTP/1.1 200 OK
{
  "count": 2
}

Get a count of all the comments for all the articles of a certain blog

GET https://apis.haravan.com/web/comments/count.json?blog_id=241253187

Details

HTTP/1.1 200 OK
{
  "count": 2
}

Get a count of all the comments for this shop

GET https://apis.haravan.com/web/comments/count.json

Details

HTTP/1.1 200 OK
{
  "count": 2
}

Receive a single Comment

GET

https://apis.haravan.com/web/comments/{comment_id}.json

Parameters

fields

comma-separated list of fields to include in the response

Get a single comment

GET https://apis.haravan.com/web/comments/118373535.json

Details

HTTP/1.1 200 OK
{
  "comment": {
    "article_id": 134645308,
    "author": "Soleone",
    "blog_id": 241253187,
    "body": "Hi author, I really _like_ what you're doing there.",
    "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
    "created_at": "2015-03-28T13:26:28-04:00",
    "email": "[email protected]",
    "id": 118373535,
    "ip": "127.0.0.1",
    "published_at": null,
    "status": "published",
    "updated_at": "2015-03-28T13:26:28-04:00",
    "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
  }
}

Create a new Comment

POST

https://apis.haravan.com/web/comments.json

Create a new comment with basic textile markup for a certain article of a blog

POST https://apis.haravan.com/web/comments.json

{
  "comment": {
    "body": "I like comments\nAnd I like posting them *RESTfully*.",
    "author": "Your name",
    "email": "[email protected]",
    "ip": "107.20.160.121",
    "blog_id": 241253187,
    "article_id": 134645308
  }
}

Details

HTTP/1.1 201 Created
{
  "comment": {
    "article_id": 134645308,
    "author": "Your name",
    "blog_id": 241253187,
    "body": "I like comments\nAnd I like posting them *RESTfully*.",
    "body_html": "<p>I like comments<br \/>\nAnd I like posting them <strong>RESTfully<\/strong>.<\/p>",
    "created_at": "2015-03-28T13:27:26-04:00",
    "email": "[email protected]",
    "id": 757536352,
    "ip": "107.20.160.121",
    "published_at": "2015-03-28T13:27:26-04:00",
    "status": "pending",
    "updated_at": "2015-03-28T13:27:26-04:00",
    "user_agent": null
  }
}

Trying to create a comment without a body, author, and email will return an error

POST https://apis.haravan.com/web/comments.json

{
  "comment": {
    "article_id": 134645308
  }
}

Details

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "author": [
      "can't be blank"
    ],
    "body": [
      "can't be blank"
    ],
    "email": [
      "is invalid"
    ]
  }
}

Modify an existing Comment

PUT

https://apis.haravan.com/web/comments/{comment_id}.json

Update a comment of an article within a blog

**Update an existing comment body**

PUT https://apis.haravan.com/web/comments/118373535.json

{
  "comment": {
    "id": 118373535,
    "body": "You can even update through a web service.",
    "author": "Your new name",
    "email": "[email protected]",
    "published_at": "2015-03-28T17:27:28+00:00"
  }
}

Details

HTTP/1.1 200 OK
{
  "comment": {
    "article_id": 134645308,
    "author": "Your new name",
    "blog_id": 241253187,
    "body": "You can even update through a web service.",
    "body_html": "<p>You can even update through a web service.<\/p>",
    "created_at": "2015-03-28T13:26:28-04:00",
    "email": "[email protected]",
    "id": 118373535,
    "ip": "127.0.0.1",
    "published_at": "2015-03-28T13:27:28-04:00",
    "status": "published",
    "updated_at": "2015-03-28T13:27:29-04:00",
    "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
  }
}

Mark a Comment as spam

POST

https://apis.haravan.com/web/comments/{comment_id}/spam.json

Mark a comment as spam

Mark a comment as spam, helping to train our spam detection as well as remove the comment sometime soon

POST https://apis.haravan.com/web/comments/653537639/spam.json

{ }

Details

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "[email protected]",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:28-04:00",
  "status": "spam",
  "updated_at": "2015-03-28T13:27:28-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}

Mark a Comment as not spam

POST

https://apis.haravan.com/web/comments/{comment_id}/not_spam.json

Mark a comment as not spam

Mark a comment as not spam, restoring a comment marked as spam back to published

POST https://apis.haravan.com/web/comments/653537639/not_spam.json

{ }

Details

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "[email protected]",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:28-04:00",
  "status": "published",
  "updated_at": "2015-03-28T13:27:28-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}

Approve a Comment

POST

https://apis.haravan.com/web/comments/{comment_id}/approve.json

Approve a comment

Approve a comment that is currently pending unapproved so that it will be published on the site

POST https://apis.haravan.com/web/comments/653537639/approve.json

{ }

Details

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "[email protected]",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:26-04:00",
  "status": "published",
  "updated_at": "2015-03-28T13:27:26-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}

Remove a Comment

POST

https://apis.haravan.com/web/comments/{comment_id}/remove.json

Remove a comment

Remove a comment

POST https://apis.haravan.com/web/comments/653537639/remove.json

{ }

Details

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "[email protected]",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:28-04:00",
  "status": "removed",
  "updated_at": "2015-03-28T13:27:28-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}

Restore a Comment

POST

https://apis.haravan.com/web/comments/{comment_id}/restore.json

Restore a Comment

POST https://apis.haravan.com/web/comments/653537639/restore.json

{ }

Details

HTTP/1.1 200 OK
{
  "article_id": 134645308,
  "author": "Soleone",
  "blog_id": 241253187,
  "body": "Hi author, I really _like_ what you're doing there.",
  "body_html": "<p>Hi author, I really <em>like<\/em> what you're doing there.<\/p>",
  "created_at": "2015-03-28T13:26:28-04:00",
  "email": "[email protected]",
  "id": 653537639,
  "ip": "127.0.0.1",
  "published_at": "2015-03-28T13:27:28-04:00",
  "status": "published",
  "updated_at": "2015-03-28T13:27:28-04:00",
  "user_agent": "Mozilla\/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us) AppleWebKit\/525.18 (KHTML, like Gecko) Version\/3.1.2 Safari\/525.20.1"
}

What you can do with Comment?​

Comment Properties​

Endpoints​

Receive a list of all Comments​

Parameters​

Receive a count of all Comments​

Parameters​

Receive a single Comment​

Parameters​

Create a new Comment​

Modify an existing Comment​

Mark a Comment as spam​

Mark a Comment as not spam​

Approve a Comment​

Remove a Comment​

Restore a Comment​

What you can do with Comment?

Comment Properties

Endpoints

Receive a list of all Comments

Parameters

Receive a count of all Comments

Parameters

Receive a single Comment

Parameters

Create a new Comment

Modify an existing Comment

Mark a Comment as spam

Mark a Comment as not spam

Approve a Comment

Remove a Comment

Restore a Comment