Comments

Add and retrieve comments for dataset discussions and collaboration.

GET /api/datasets/{id}/comments

Get all top-level comments (threads) for a dataset.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug

Response:

{
  "_links": {
    "self": { "href": "/api/datasets/{id}/comments" }
  },
  "_embedded": {
    "inf:comment": [
      {
        "id": "comment-123",
        "message": "Updated the sales figures for Q1. Please review.",
        "datasetId": "sales-2024",
        "userId": "user:admin",
        "user": {
          "id": "user:admin",
          "name": "Admin User",
          "email": "admin@example.com"
        },
        "parentId": null,
        "createdAt": "2024-02-08T15:30:00Z",
        "updatedAt": "2024-02-08T15:30:00Z",
        "replies": []
      },
      {
        "id": "comment-456",
        "message": "The West region numbers look inconsistent. Can someone verify?",
        "datasetId": "sales-2024",
        "userId": "user:analyst1",
        "user": {
          "id": "user:analyst1",
          "name": "Analyst User",
          "email": "analyst@example.com"
        },
        "parentId": null,
        "createdAt": "2024-02-07T10:15:00Z",
        "updatedAt": "2024-02-07T10:15:00Z",
        "replies": [
          {
            "id": "comment-789",
            "message": "Verified - the numbers are correct. There was a large order in January.",
            "parentId": "comment-456",
            "userId": "user:admin",
            "createdAt": "2024-02-07T14:20:00Z"
          }
        ]
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

Behavior:

• Returns only top-level comments (parentId: null)
• Comments are sorted by createdAt descending (newest first)
• Replies are included in nested replies array

---

POST /api/datasets/{id}/comments

Post a new comment on a dataset.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug

Request Body:

Field	Type	Required	Description
message	string	Yes	Comment text
parentId	string	No	Parent comment ID for replies

Example Request (new thread):

{
  "message": "Please review the updated profit margin calculations."
}

Example Request (reply):

{
  "message": "Looks good! Approved for publication.",
  "parentId": "comment-123"
}

Response:

{
  "id": "comment-999",
  "message": "Please review the updated profit margin calculations.",
  "datasetId": "sales-2024",
  "userId": "user:admin",
  "user": {
    "id": "user:admin",
    "name": "Admin User"
  },
  "parentId": null,
  "createdAt": "2024-02-08T16:00:00Z",
  "updatedAt": "2024-02-08T16:00:00Z"
}

Activity Creation:

When a comment is posted, an Activity record is created:

{
  "type": "dataset.comment.created",
  "userId": "user:admin",
  "datasetId": "sales-2024",
  "commentId": "comment-999",
  "message": "Please review the updated profit margin calculations.",
  "createdAt": "2024-02-08T16:00:00Z"
}

This triggers notifications to:

• Dataset owner
• Users subscribed to dataset
• Parent comment author (for replies)

---

Use Cases

Collaboration

// Data wizard posts question
await POST('/api/datasets/sales-2024/comments', {
  message: 'Should we exclude returns from total sales?'
});

// Team member replies
await POST('/api/datasets/sales-2024/comments', {
  message: 'Yes, returns should be in a separate field.',
  parentId: 'comment-question-123'
});

Change Notifications

// Notify team of updates
await POST('/api/datasets/sales-2024/comments', {
  message: 'Updated Q1 data - added February actuals. Refresh needed.'
});

Review Workflow

// Request review
await POST('/api/datasets/financial-report/comments', {
  message: '@finance-team: Ready for final review before publishing.'
});

// Approval
await POST('/api/datasets/financial-report/comments', {
  message: 'Approved ✓',
  parentId: 'comment-review-request'
});

---

Best Practices

• Be descriptive - Provide context in comments
• Use threads - Reply to related comments
• Notify relevant users - Mention teams/users with @ syntax
• Track decisions - Document important choices in comments
• Clean up - Archive or delete outdated comment threads