Comments API in Wasabi AiR

The Comments API enables you to comment on any item in Wasabi AiR. The target item is defined by the target_type and target_id fields, which together can refer to any item. The primary use case is for commenting on items, where target_type is "item".

Creating a Comment

To create a comment, send a request:

POST /api/data/comments
{
    "target_type": "{target_type}",
    "target_id": "{target_id}",
    "body": "{body}",
    "time_marker": {time_marker}
}

• {target_type} - (string) The type of target (for example, item). This field annot be longer than 32 characters.
• {target_id} - (string) The ID of the target. This field annot be longer than 32 characters. 
• {body} - (string) The body of the comment to add. This field can be a variable size. Markdown is an acceptable input for body, although some HTML tags could be stripped if considered dangerous.  
• {time_marker} - (string) Optional. A time marker in hh:mm:ss:ms format. This field can range from 00:00:00:00 to 99:59:59:99.

Response

The response is a JSON document with a single comment created. For example:

{
	"id": "58bf31b6dd76f671d748346e2d701f60",
	"target_type": "item",
	"target_id": "07690219bd7a33d2671531daa46c2b2d",
	"body": "Comment with time marker!",
	"ctime": "2017-03-07T22:18:30.99403Z",
	"author": {
		"id": "58bf3103d9eb050f98c9c0ec6f177111",
		"email": "jdoe@example.com",
		"first_name": "John",
		"last_name": "Doe",
		"enabled": true,
		"company_uid": ""
	},
	"deleted": false,
	"time_marker": "00:04:23:87"
}

Getting Comments

To get a list of comments for a specific target type and ID:

GET /api/data/comments?target_type={target_type}&target_id={target_id}&page={page_number}

• {target_type} - (string) The type of target (for example, item).
• {target_id} - (string) The ID of the target (usually UUID type).
• {page_number} - (int) A zero-indexed page number.

Response

The response is a JSON document containing the page number, comments, and author information for each comment. For example:

{
	"page": 0,
	"comments": [
		{
			"id": "58bf31b6dd76f671d748346e2d701f60",
			"target_type": "item",
			"target_id": "07690219bd7a33d2671531daa46c2b2d",
			"body": "Comment with time marker!",
			"ctime": "2017-03-07T22:18:30.99403Z",
			"author": {
				"id": "58bf3103d9eb050f98c9c0ec6f177111",
				"email": "jdoe@example.com",
				"first_name": "John",
				"last_name": "Doe",
				"enabled": true,
				"company_uid": ""
			},
			"deleted": false,
			"time_marker": "00:04:23:87"
		},
		{
			"id": "58bf31ef481ccf895a85a0e6eca63d54",
			"target_type": "item",
			"target_id": "07690219bd7a33d2671531daa46c2b2d",
			"body": "Another comment...",
			"ctime": "2017-03-07T22:19:27.676069Z",
			"author": {
				"id": "58bf3103d9eb050f98c9c0ec6f177111",
				"email": "jdoe@example.com",
				"first_name": "John",
				"last_name": "Doe",
				"enabled": true,
				"company_uid": ""
			},
			"deleted": false,
			"time_marker": ""
		}
	]
}

Deleting a Comment

To delete a comment:

DELETE /api/data/comments/{comment_id}

• {comment_id} - (string) A comment ID to be deleted.

Response

The response contains HTTP status 200 if deleting a comment is successful. Only the comment author and administrators can remove comments.

Updating a Comment

To update a comment, send a request containing fields from the original comment with a new body:

PUT /api/data/comments
{
    "id": "{id}",
    "body": "{new_body}",
    "target_type": "{target_type}",
    "target_id": "{target_id}",
    "author": {
        "id": "{author_id}"
    }
}

• {id} - (string) The ID of the original comment to update.
• {new_body} - (string) The updated body for the comment.
• {target_type} - (string) The type of the target.
• {target_id} - (string) The ID of the target.
• {author_id} - (string) The only required field from the original author JSON field.

Only the comment author and administrators can perform this operation.

Sample Response

{
	"id": "58bf328ab55f8b7b299d9734714aa1ba",
	"parent_id": "58bf31ef481ccf895a85a0e6eca63d54",
	"target_type": "item",
	"target_id": "07690219bd7a33d2671531daa46c2b2d",
	"body": "Modified comment.",
	"ctime": "2017-03-07T22:22:02.851359Z",
	"author": {
		"id": "58bf3103d9eb050f98c9c0ec6f177111",
		"email": "jdoe@example.com",
		"first_name": "John",
		"last_name": "Doe",
		"enabled": true,
		"company_uid": ""
	},
	"deleted": false,
	"time_marker": ""
}

Getting the Edit History of a Comment

To get the comment history for modified comments, send a request:

GET /api/data/comments/{comment_id}/history

• {comment_id} - The ID of the comment from which to get the edit history.

Response

The response is a JSON document with all comment modifications, sorted by date. For example:

{
	"page": 0,
	"comments": [
		{
			"id": "58bf31ef481ccf895a85a0e6eca63d54",
			"target_type": "item",
			"target_id": "07690219bd7a33d2671531daa46c2b2d",
			"body": "Another comment...",
			"ctime": "2017-03-07T22:19:27.676069Z",
			"author": {
				"id": "58bf3103d9eb050f98c9c0ec6f177111",
				"email": "jdoe@example.com",
				"first_name": "John",
				"last_name": "Doe",
				"enabled": true,
				"company_uid": ""
			},
			"deleted": true,
			"time_marker": ""
		},
		{
			"id": "58bf328ab55f8b7b299d9734714aa1ba",
			"target_type": "item",
			"target_id": "07690219bd7a33d2671531daa46c2b2d",
			"body": "Modified comment.",
			"ctime": "2017-03-07T22:22:02.851359Z",
			"author": {
				"id": "58bf3103d9eb050f98c9c0ec6f177111",
				"email": "jdoe@example.com",
				"first_name": "John",
				"last_name": "Doe",
				"enabled": true,
				"company_uid": ""
			},
			"deleted": true,
			"time_marker": ""
		}
	]
}