Beanstalk

Comment Resource

Every changeset and file in Beanstalk can have comments associated with it. Changesets can have comments for code lines (diff pieces) and for changeset as a whole. Comments on files should always be associated with a line of code.

Readable attributes

id integer Unique UD of Comment
account_id integer ID of the associated Account
repository_id integer ID of the associated Repository
author_id integer ID of the User who created the Comment
author_name string Full name of the User
author_email string Email address of the User
author_login string Login of the User
revision string Revision number (or SHA1 hash) of the associated commit
origin string Either “changeset” or “file”. Page where the comment was created
file_path string File path for which comment was created
line_num integer Line number if comment was made for a line of code. For comments made on diff pieces (changeset page) this will be right line number
line_num_left integer Left line number. For comments created on changeset page only (comments on diff pieces)
body string Contents of the Comment (raw Markdown)
rendered_body string Contents of the Comment with Markdown rendering applied. Generated automatically
line_contents string For comments created on lines of code only. Contains contents of the line on which the comment was made.
updated_at datetime Time when the Comment was last updated
created_at datetime Time when the Comment was first added to the system

Writable attributes

revision string Required
body string Required

Note on formatting

Beanstalk will automatically escape all HTML tags from the body attribute, apply Markdown formatting and turn all URls into clickable HTML links.

Find All Comments for Repository

Optional GET parameters:

  • page (integer) — page number for pagination;
  • per_page (integer) — number of elements per page (default 15, maximum 50).
json http-request 
GET /api/{REPOSITORY_ID}/comments.json

Click to expand…

json http-response 
[{
  "comment": { 
    "file_path": "",
    "created_at": "2011/10/05 13:10:00 +0800",
    "author_login": "ilya",
    "body": "Shikaka",
    "author_name": "John Doe",
    "updated_at": "2011/10/05 13:10:00 +0800",
    "account_id": 2,
    "rendered_body": "\u003Cp\u003EShikaka\u003C/p\u003E",
    "id": 2,
    "revision": "7ada704eac04075f763f36190716e43381fc6e1d",
    "author_id": 2,
    "author_email": "ilya@example.com",
    "repository_id": 3,
    "line_num": 322,
    "line_num_left": 320,
    "line_contents": "+ original line of code here",
    "origin": "changeset"
  }
},{
  "comment": {
    "file_path": "",
    "created_at": "2011/10/05 13:10:09 +0800",
    "author_login": "ilya",
    "body": "Shikaka",
    "author_name": "John Doe",
    "updated_at": "2011/10/05 13:10:09 +0800",
    "account_id": 2,
    "rendered_body": "\u003Cp\u003EShikaka\u003C/p\u003E",
    "id": 3,
    "revision": "7ada704eac04075f763f36190716e43381fc6e1d",
    "author_id": 2,
    "author_email": "ilya@example.com",
    "repository_id": 3,
    "line_num": 322,
    "line_num_left": 320,
    "line_contents": "+ original line of code here",
    "origin": "changeset"
  }
}]
xml http-request 
GET /api/{REPOSITORY_ID}/comments.xml

Click to expand…

xml http-response 
<?xml version="1.0" encoding="UTF-8"?>
<comments type="array">
  <comment>
    <id type="integer">324934</id>
    <account-id type="integer">4</account-id>
    <author-id type="integer">17</author-id>
    <author-name>John Doe</author-id>
    <author-login>ilya-sabanin</author-login>
    <author-email>ilya@example.com</author-email>
    <body>
      Hey, this is my first comment.
      I think you have a typo on this line.
    </body>
    <created-at type="datetime">2010-01-18T15:47:45Z</created-at>
    <file-path>trunk/index.html</file-path>
    <rendered-body>
      &lt;p&gt;Hey, this is my first comment.
      I think you have a typo on this line.&lt;/p&gt;
    </rendered-body>
    <repository-id type="integer">2</repository-id>
    <revision type="integer">1</revision>
    <updated-at type="datetime">2010-01-18T15:47:45Z</updated-at>
    <line-num type="integer" nil="true"/>
    <line-num-left type="integer" nil="true"/>
    <line-contents nil="true"/>
    <origin>changeset</origin>
  </comment>
  <comment>
    <id type="integer">834234</id>
    <account-id type="integer">4</account-id>
    <author-id type="integer">17</author-id>
    <author-name>John Doe</author-id>
    <author-login>ilya-sabanin</author-login>
    <author-email>ilya@example.com</author-email>
    <body>Check out my *textile* dude.</body>
    <created-at type="datetime">2010-01-18T15:48:54Z</created-at>
    <file-path nil="true"></file-path>
    <rendered-body>
      &lt;p&gt;Check out my <strong>textile</strong> dude.&lt;/p&gt;
    </rendered-body>
    <repository-id type="integer">2</repository-id>
    <revision type="integer">66</revision>
    <updated-at type="datetime">2010-01-18T15:48:54Z</updated-at>
    <line-num type="integer" nil="true"/>
    <line-num-left type="integer" nil="true"/>
    <line-contents nil="true"/>
    <origin>changeset</origin>
  </comment>
</comments>

Find All Comments for Changeset

Optional GET parameters:

  • page (integer) — page number for pagination;
  • per_page (integer) — number of elements per page (default 15, maximum 50).
json http-request 
GET /api/{REPOSITORY_ID}/comments.json?revision={REVISION}

Click to expand…

json http-response 
[{
  "comment": { 
    "file_path": "",
    "created_at": "2011/10/05 13:10:00 +0800",
    "author_login": "ilya",
    "body": "Shikaka",
    "author_name": "John Doe",
    "updated_at": "2011/10/05 13:10:00 +0800",
    "account_id": 2,
    "rendered_body": "\u003Cp\u003EShikaka\u003C/p\u003E",
    "id": 2,
    "revision": "7ada704eac04075f763f36190716e43381fc6e1d",
    "author_id": 2,
    "author_email": "ilya@example.com",
    "repository_id": 3,
    "line_num": 322,
    "line_num_left": 320,
    "line_contents": "+ original line of code here",
    "origin": "changeset"
  }
},{
  "comment": {
    "file_path": "",
    "created_at": "2011/10/05 13:10:09 +0800",
    "author_login": "ilya",
    "body": "Shikaka",
    "author_name": "John Doe",
    "updated_at": "2011/10/05 13:10:09 +0800",
    "account_id": 2,
    "rendered_body": "\u003Cp\u003EShikaka\u003C/p\u003E",
    "id": 3,
    "revision": "7ada704eac04075f763f36190716e43381fc6e1d",
    "author_id": 2,
    "author_email": "ilya@example.com",
    "repository_id": 3,
    "line_num": 322,
    "line_num_left": 320,
    "line_contents": "+ original line of code here",
    "origin": "changeset"
  }
}]
xml http-request 
GET /api/{REPOSITORY_ID}/comments.xml?revision={REVISION}

Click to expand…

xml http-response 
<?xml version="1.0" encoding="UTF-8"?>
<comments type="array">
  <comment>
    <id type="integer">583197</id>
    <account-id type="integer">4</account-id>
    <author-id type="integer">17</author-id>
    <author-name>John Doe</author-id>
    <author-login>ilya-sabanin</author-login>
    <author-email>ilya@example.com</author-email>
    <body>
      Hey, this is my first comment.
      I think you have a typo on this line.
    </body>
    <created-at type="datetime">2010-01-18T15:47:45Z</created-at>
    <file-path>trunk/index.html</file-path>
    <rendered-body>
      &lt;p&gt;Hey, this is my first comment.
      I think you have a typo on this line.&lt;/p&gt;
    </rendered-body>
    <repository-id type="integer">2</repository-id>
    <revision type="integer">1</revision>
    <updated-at type="datetime">2010-01-18T15:47:45Z</updated-at>
    <line-num type="integer" nil="true"/>
    <line-num-left type="integer" nil="true"/>
    <line-contents nil="true"/>
    <origin>changeset</origin>
  </comment>
</comments>

Find All Comments for User

Returns an array of comments by a specific user across all repositories.

Admins can use user_id parameter to specify ID of any user from the account. Regular users can use method without user_id to receive their comments only.

Optional GET parameters:

  • page (integer) — page number for pagination;
  • per_page (integer) — number of elements per page (default 15, maximum 50).
json http-request 
GET /api/comments/user.json?user_id={USER_ID}

Click to expand…

json http-response 
[{
  "comment": { 
    "file_path": "",
    "created_at": "2011/10/05 13:10:00 +0800",
    "author_login": "ilya",
    "body": "Shikaka",
    "author_name": "John Doe",
    "updated_at": "2011/10/05 13:10:00 +0800",
    "account_id": 2,
    "rendered_body": "\u003Cp\u003EShikaka\u003C/p\u003E",
    "id": 2,
    "revision": "7ada704eac04075f763f36190716e43381fc6e1d",
    "author_id": 2,
    "author_email": "ilya@example.com",
    "repository_id": 3,
    "line_num": 322,
    "line_num_left": 320,
    "line_contents": "+ original line of code here",
    "origin": "changeset"
  }
},{
  "comment": {
    "file_path": "",
    "created_at": "2011/10/05 13:10:09 +0800",
    "author_login": "ilya",
    "body": "Shikaka",
    "author_name": "John Doe",
    "updated_at": "2011/10/05 13:10:09 +0800",
    "account_id": 2,
    "rendered_body": "\u003Cp\u003EShikaka\u003C/p\u003E",
    "id": 3,
    "revision": "7ada704eac04075f763f36190716e43381fc6e1d",
    "author_id": 2,
    "author_email": "ilya@example.com",
    "repository_id": 3,
    "line_num": 322,
    "line_num_left": 320,
    "line_contents": "+ original line of code here",
    "origin": "changeset"
  }
}]
xml http-request 
GET /api/comments/user.xml?user_id={USER_ID}

Click to expand…

xml http-response 
<?xml version="1.0" encoding="UTF-8"?>
<comments type="array">
  <comment>
    <id type="integer">583197</id>
    <account-id type="integer">4</account-id>
    <author-id type="integer">345661</author-id>
    <author-name>John Doe</author-id>
    <author-login>ilya-sabanin</author-login>
    <author-email>ilya@example.com</author-email>
    <body>
      Hey, this is my first comment.
      I think you have a typo on this line.
    </body>
    <created-at type="datetime">2010-01-18T15:47:45Z</created-at>
    <file-path>trunk/index.html</file-path>
    <rendered-body>
      &lt;p&gt;Hey, this is my first comment.
      I think you have a typo on this line.&lt;/p&gt;
    </rendered-body>
    <repository-id type="integer">2</repository-id>
    <revision type="integer">1</revision>
    <updated-at type="datetime">2010-01-18T15:47:45Z</updated-at>
    <line-num type="integer" nil="true"/>
    <line-num-left type="integer" nil="true"/>
    <line-contents nil="true"/>
    <origin>changeset</origin>
  </comment>
</comments>

Find Comment

json http-request 
GET /api/{REPOSITORY_ID}/comments/{COMMENT_ID}.json

Click to expand…

json http-response 
"comment": {
  "file_path": "",
  "created_at": "2011/10/05 13:10:09 +0800",
  "author_login": "ilya",
  "body": "Shikaka",
  "author_name": "John Doe",
  "updated_at": "2011/10/05 13:10:09 +0800",
  "account_id": 2,
  "rendered_body": "\u003Cp\u003EShikaka\u003C/p\u003E",
  "id": 3,
  "revision": "7ada704eac04075f763f36190716e43381fc6e1d",
  "author_id": 2,
  "author_email": "ilya@example.com",
  "repository_id": 3,
  "line_num": 322,
  "line_num_left": 320,
  "line_contents": "+ original line of code here",
  "origin": "changeset"
}
xml http-request 
GET /api/{REPOSITORY_ID}/comments/{COMMENT_ID}.xml

Click to expand…

xml http-response 
<?xml version="1.0" encoding="UTF-8"?>
<comment>
  <id type="integer">8543</id>
  <account-id type="integer">4</account-id>
  <author-id type="integer">17</author-id>
  <author-name>John Doe</author-id>
  <author-login>ilya-sabanin</author-login>
  <author-email>ilya@example.com</author-email>
  <body>Hey, this is my first comment.</body>
  <created-at type="datetime">2010-01-18T15:47:45Z</created-at>
  <file-path>trunk/index.html</file-path>
  <rendered-body>
    &lt;p&gt;Hey, this is my first comment.&lt;/p&gt;
  </rendered-body>
  <repository-id type="integer">2</repository-id>
  <revision type="integer">1</revision>
  <updated-at type="datetime">2010-01-18T15:47:45Z</updated-at>
  <line-num type="integer" nil="true"/>
  <line-num-left type="integer" nil="true"/>
  <line-contents nil="true"/>
  <origin>changeset</origin>
</comment>

Create Comment

json http-request 
POST /api/{REPOSITORY_ID}/comments.json
{
  "comment": {
    "body": "Shikaka 2",
    "revision": "7ada704eac04075f763f36190716e43381fc6e1d"
  }
}

Click to expand…

json http-response 
{
  "comment": {
    "file_path": "",
    "created_at": "2011/10/05 13:10:09 +0800",
    "author_login": "ilya",
    "body": "Shikaka",
    "author_name": "John Doe",
    "updated_at": "2011/10/05 13:10:09 +0800",
    "account_id": 2,
    "rendered_body": "\u003Cp\u003EShikaka\u003C/p\u003E",
    "id": 3,
    "revision": "7ada704eac04075f763f36190716e43381fc6e1d",
    "author_id": 2,
    "author_email": "ilya@example.com",
    "repository_id": 3,
    "line_num": null,
    "line_num_left": null,
    "line_contents": null,
    "origin": "changeset"
  }
}
xml http-request 
POST /api/{REPOSITORY_ID}/comments.xml
<comment>
  <revision type="integer">6</revision>
  <body>This is my comment text.</body>
</comment>

Click to expand…

xml http-response 
<?xml version="1.0" encoding="UTF-8"?>
<comment>
  <id type="integer">98636</id>
  <account-id type="integer">4</account-id>
  <author-id type="integer">17</author-id>
  <author-name>John Doe</author-id>
  <author-login>ilya-sabanin</author-login>
  <author-email>ilya@example.com</author-email>
  <body>This is my comment text.</body>
  <created-at type="datetime">2010-01-18T15:47:45Z</created-at>
  <file-path>/branches/application/super_file.txt</file-path>
  <rendered-body>
    &lt;p&gt;This is my comment text.&lt;/p&gt;
  </rendered-body>
  <repository-id type="integer">2</repository-id>
  <revision type="integer">6</revision>
  <updated-at type="datetime">2010-01-18T15:47:45Z</updated-at>
  <line-num type="integer" nil="true"/>
  <line-num-left type="integer" nil="true"/>
  <line-contents nil="true"/>
  <origin>changeset</origin>
</comment>

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Body can't be blank</error>
</errors>