Comments

Commenting is a feature that allows your site visitors to comment on web pages for any content object.

You can retrieve a list of all existing comments, add new comments, reply to existing comments, or delete a comment.

Listing Comments

You can list the existing comment on a content object by sending a GET request to the URL of the content object and appending /@comments:

GET /events/event-1/@comments HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.getComments({
  token: login.data.token,
  path: '/events/event-1',
});

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:8080/events/event-1/@comments",
  "items": [
    {
      "@id": "http://localhost:8080/events/event-1/@comments/3d61035e-1fd3-435a-85a8-c44863f3a2dd",
      "@parent": null,
      "author_name": "",
      "author_username": "admin",
      "can_reply": true,
      "comment_id": "3d61035e-1fd3-435a-85a8-c44863f3a2dd",
      "creation_date": "2022-04-02T20:10:00.000Z",
      "in_reply_to": null,
      "is_deletable": true,
      "is_editable": true,
      "modification_date": "2022-04-02T20:10:00.000Z",
      "text": {
        "data": "Comment 1",
        "mime-type": "text/plain"
      }
    },
    {
      "@id": "http://localhost:8080/events/event-1/@comments/4d61035e-1fd3-435a-85a8-c44863f3a2dd",
      "@parent": "http://localhost:8080/events/event-1/@comments/3d61035e-1fd3-435a-85a8-c44863f3a2dd",
      "author_name": "",
      "author_username": "admin",
      "can_reply": true,
      "comment_id": "4d61035e-1fd3-435a-85a8-c44863f3a2dd",
      "creation_date": "2022-04-02T20:10:00.000Z",
      "in_reply_to": "3d61035e-1fd3-435a-85a8-c44863f3a2dd",
      "is_deletable": true,
      "is_editable": true,
      "modification_date": "2022-04-02T20:10:00.000Z",
      "text": {
        "data": "Comment 1.1",
        "mime-type": "text/plain"
      }
    }
  ],
  "items_total": 2,
  "permissions": {
    "can_reply": true,
    "view_comments": true
  }
}

The following fields are returned.

  • @id: Link to the current endpoint
  • items: a list of comments for the current resource
  • items_total: the total number of comments for the resource

The items attribute returns a list of comments. Each comment provides the following fields.

  • @id: hyperlink to the comment
  • @parent: (optional) the parent comment
  • author_name: the full name of the author of this comment
  • author_username: the username of the author of this comment
  • comment_id: the comment ID uniquely identifies the comment
  • in_reply_to: the comment ID of the parent comment
  • creation_date: when the comment was placed
  • `modification_date: when the comment was last updated
  • text: contains a mime-type and text attribute with the text of the comment. Default mime-type is text/plain.

Adding a Comment

To add a new comment to a content object, send a POST request to the URL of the content object and append /@comments to the URL. The body of the request needs to contain a JSON structure with a text attribute that contains the comment text:

POST /events/event-1/@comments HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "text": "New comment"
}

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.addComment({
  token: login.data.token,
  path: '/events/event-1',
  data: {
    text: 'New comment',
  },
});

Example response:

HTTP/1.1 204 No Content

Replying to a Comment

To add a direct reply to an existing comment, send a POST request to the URL of the comment to which you want to reply. The body of the request needs to contain a JSON structure with a text attribute that contains the comment text:

POST /events/event-1/@comments/3d61035e-1fd3-435a-85a8-c44863f3a2dd HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "text": "New sub comment"
}

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.replyComment({
  token: login.data.token,
  path: '/events/event-1',
  params: {
    id: '3d61035e-1fd3-435a-85a8-c44863f3a2dd',
  },
  data: {
    text: 'New comment',
  },
});

Example response:

HTTP/1.1 204 No Content

Updating a Comment

An existing comment can be updated by sending a PATCH request to the URL of the comment. The request body needs to contain a JSON structure with at least a text attribute:

PATCH /events/event-1/@comments/3d61035e-1fd3-435a-85a8-c44863f3a2dd HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "text": "Updated comment"
}

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.updateComment({
  token: login.data.token,
  path: '/news/my-news-item',
  params: {
    id: '3d61035e-1fd3-435a-85a8-c44863f3a2dd',
  },
  data: {
    text: 'Updated comment',
  },
});

Example response:

HTTP/1.1 204 No Content

Deleting a Comment

An existing comment can be deleted by sending a DELETE request to the URL of the comment.

DELETE /events/event-1/@comments/3d61035e-1fd3-435a-85a8-c44863f3a2dd HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.deleteComment({
  token: login.data.token,
  params: {
    id: '3d61035e-1fd3-435a-85a8-c44863f3a2dd',
  },
});

Example response:

HTTP/1.1 204 No Content
This site uses Just the Docs, a documentation theme for Jekyll.