My favorites | Sign in
Logo
          
Search
for
Updated Nov 05, 2009 by mar...@myd0.de
Labels: Featured
ReviewBoardAPI  
Documentation for the public Review Board API

Review Board API Documentation

All web services return JSON formatted data. See http://json.org for a full description of JavaScript Object Notation.

You must request all methods marked with "POST Required" with an HTTP POST method rather than GET. i.e. This will fail and return an HTTP status of 405: http://demo.review-board.org/api/json/accounts/login/?username=jay&password=password

All methods marked with Login Required require you to send a login cookie to verify your credentials. Use the accounts/login method to get this cookie.

All JSON responses contain a "stat" field that either has a value of "ok" on success or "fail" on failure.

Error Handling

On error "stat" will be set to "fail" and there will be an "err" field that contains "msg" and "code".

Error Response Example:

{
    "stat": "fail", 
    "err": {
        "msg": "You are not logged in", 
        "code": 103
    }
}

List of possible error codes

Methods

/api/json/accounts/login/

POST Required

Login to reviewboard. Sets an HTTP cookie that must be presented all most other API calls.

Required Arguments

Example Response

{"stat": "ok"}

/api/json/repositories/

Login Required

Returns a list of all known repositories.

Arguments

None

Example Response

{
   "stat":"ok",
   "repositories":[
      {
         "path":"http:\/\/reviewboard.googlecode.com\/svn",
         "tool":"Subversion",
         "id":1,
         "name":"Review Board SVN"
      },
      {
         "path":"http:\/\/svn.navi.cx\/misc",
         "tool":"Subversion",
         "id":2,
         "name":"Navi"
      }
   ]
}

/api/json/users/

Login Required

Returns a list of all users. If the query parameter is passed, users with a username beginning with the query value will be returned. Note that query must be passed in as a GET parameter, not with a POST

Optional Arguments

Example Response

{
   "stat":"ok",
   "users": [
      {
         "username":"bovik",
         "first_name":"Harold",
         "last_name":"Bovik"
      },
      {
         "username":"chkr",
         "first_name":"Christian",
         "last_name":"Krause"
      },
   ] 
}

/api/json/groups/

Login Required

Returns a list of all review groups. If the query parameter is passed, groups with a name beginning with the query value will be returned. Note that query must be passed in as a GET parameter, not with a POST

Optional Arguments

Example Response

{
   "stat":"ok",
   "groups":[
      {
         "display_name":"Review Board",
         "name":"reviewboard"
      }
   ]
}

/api/json/groups/<group_name>/star/

Login Required.

Adds a group to the user's watched groups list.

Arguments

None

Example Response

{"stat": "ok"}

/api/json/groups/<group_name>/unstar/

Login Required.

Removes a group from the user's watched groups list.

Arguments

None

Example Response

{"stat": "ok"}

/api/json/reviewrequests/all/

/api/json/reviewrequests/to/group/<group_name>/

/api/json/reviewrequests/to/user/<username>/

/api/json/reviewrequests/from/user/<username>/

/api/json/reviewrequests/repository/<repository_id>/changenum/<changenum>/

Login Required GET Required

Return a list of reviews that match:

Optional Arguments

Example Response

{
   "stat":"ok",
   "review_requests":[
      {
         "status":"pending",
         "bugs_closed":"",
         "last_updated":"2007-12-03 10:00:11",
         "description":"foo bar",
         "repository":{
            "path":"http:\/\/reviewboard.googlecode.com\/svn",
            "tool":"Subversion",
            "id":1,
            "name":"Review Board SVN"
         },
         "target_groups":[
            {
               "url":"\/groups\/reviewboard\/",
               "id":1,
               "mailing_list":"reviewboard-reviews@googlegroups.com",
               "name":"reviewboard"
            }
         ],
         "public":1,
         "changenum":null,
         "target_people":[
         ],
         "testing_done":"",
         "branch":"",
         "submitter":{
            "username":"senthil",
            "first_name":"senthil",
            "last_name":"gandhi",
            "url":"\/users\/senthil\/",
            "email":"gsn.coldfire@gmail.com",
            "fullname":"senthil gandhi",
            "id":1354
         },
         "time_added":"2007-11-30 12:06:04",
         "summary":"Screen shot for problem diff",
         "id":148
      },
   ]
}

/api/json/reviewrequests/all/count/

/api/json/reviewrequests/to/group/<group_name>/count/

/api/json/reviewrequests/to/user/<username>/count/

/api/json/reviewrequests/from/user/<username>/count/

Login Required GET Required

Returns the number review requests that are outstanding for all, in a group, to or from a user.

Optional Arguments

Example Response

{
   "count":13,
   "stat":"ok"
}

/api/json/reviewrequests/new/

Login Required. Requires POST

Creates a new review request.

Required Arguments

Optional Arguments

Example Response

{
   "stat":"ok",
   "review_request":{
      "status":"pending",
      "bugs_closed":"",
      "last_updated":"2008-02-24 10:27:38",
      "description":"",
      "repository":{
         "path":"http:\/\/reviewboard.googlecode.com\/svn",
         "tool":"Subversion",
         "id":1,
         "name":"Review Board SVN"
      },
      "target_groups":[
      ],
      "public":false,
      "changenum":null,
      "target_people":[
      ],
      "testing_done":"",
      "branch":"",
      "submitter":{
         "username":"jay",
         "first_name":"Jay",
         "last_name":"Buffington",
         "url":"\/users\/jay\/",
         "email":"jaybuffington@gmail.com",
         "fullname":"Jay Buffington",
         "id":2299
      },
      "time_added":"2008-02-24 10:27:38",
      "summary":"",
      "id":201
   }
}

/api/json/reviewrequests/<review_request_id>/

Login Required.

Returns a review request with the specified changenum.

Arguments

None

Example Response

{
   "stat":"ok",
   "review_request":{
      "status":"submitted",
      "bugs_closed":[
         "138"
      ],
      "last_updated":"2007-06-26 11:44:44",
      "description":"When bugs_closed is blank and a ReviewRequest is encoded by the JSON encoder, the following line throws an error:\nbugs_closed = [int(b.strip()) for b in o.bugs_closed.split(',')]\n''.split(',') returns (as documented) the original string in a list, being ['']. This is iterated (it contains an item) and is passed to int, thus int('') is called, throwing an error.\n\nThe fix shown works, but does add a little extra cruft to the line. Perhaps this could be split over multiple lines or otherwise abstracted.",
      "repository":{
         "path":"http:\/\/reviewboard.googlecode.com\/svn",
         "tool":"Subversion",
         "id":1,
         "name":"Review Board SVN"
      },
      "target_groups":[
         {
            "url":"\/groups\/reviewboard\/",
            "id":1,
            "mailing_list":"reviewboard-reviews@googlegroups.com",
            "name":"reviewboard"
         }
      ],
      "public":1,
      "changenum":null,
      "target_people":[
      ],
      "testing_done":"",
      "branch":"",
      "submitter":{
         "username":"testuser",
         "first_name":"Test",
         "last_name":"User",
         "url":"\/users\/testuser\/",
         "email":"testuser@example.com",
         "fullname":"Test User",
         "id":572
      },
      "time_added":"2007-06-26 07:58:40",
      "summary":"fix int() error when list of bugs is blank",
      "id":100
   }
}

/api/json/reviewrequests/<review_request_id>/star/

Login Required

Mark this review request stared to put it under the logged in user's "starred reviews"

Arguments

None

Example Response

{"stat": "ok"}

/api/json/reviewrequests/<review_request_id>/unstar/

Login Required

Remove the star from this review request so it no longer shows up in the logged in user's "starred reviews"

Arguments

None

Example Response

{"stat": "ok"}

/api/json/reviewrequests/<review_request_id>/delete/

Login Required Permission Required

Delete this review request.

Arguments

None

Example Response

{"stat": "ok"}

/api/json/reviewrequests/<review_request_id>/update_from_changenum/

Login Required Requires POST

Arguments

None

Example Response

/api/json/reviewrequests/<review_request_id>/draft/save/

Login Required Requires POST

Required Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/draft/discard/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/draft/set/<field_name>/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/draft/set/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/draft/save/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/draft/publish/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/draft/delete/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/draft/comments/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/diff/

Arguments

None

Example Response

{
    "stat": "ok",
    "diffsets": [
        {
            "timestamp": "2009-07-12 14:05:34",
            "revision": 1,
            "id": 1,
            "repository": {
                "path": "file:///path/to/repos",
                "tool": "Subversion",
                "id": 1,
                "name": "Test"
            },
            "name": "test.diff"
        }
    ]
}

/api/json/reviewrequests/<review_request_id>/reviews/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/count/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/<review_id>/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/<review_id>/comments/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/<review_id>/comments/count/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/<review_id>/replies/draft/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/<review_id>/replies/draft/save/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/<review_id>/replies/draft/discard/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/<review_id>/replies/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/reviews/<review_id>/replies/count/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/diff/new/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/screenshot/new/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/diff/<diff_revision>/file/<filediff_id>/line/<line>/comments/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/diff/<diff_revision>-<interdiff_revision>/file/<filediff_id>-<interfilediff_id>/line/<line>/comments/

Login Required Requires POST

Arguments

Example Response

/api/json/reviewrequests/<review_request_id>/s/<screenshot_id>/comments/<w>x<h>+<x>+<y>/

Login Required Requires POST

Arguments

Example Response


 

Comment by glongman, Nov 27, 2008

lots of undocumented calls here

Comment by glongman, Nov 27, 2008

a cookie for an api? not good.

Comment by helder, Mar 21, 2009

Could anyone document better the diff/new call please?

Comment by sameerud, Aug 31, 2009

How can get I get count of all reviews including closed ones?

Comment by p...@swooby.com, Oct 29, 2009

Example Python code:

import simplejson
import sys
import urllib

class ReviewBoard:
  def __init__(self, server, username, password):
    self.server = server
    self.username = username
    self.password = password
  
  def Run(self, command, params=None, throw=True):
    if params:
      params = urllib.urlencode(params)
    url = 'http://%s/api/json/%s/' % (self.server, command)
    f = urllib.urlopen(url, params)
    # TODO: Request Error handling...
    s = f.read()
    response = simplejson.loads(s)
    self.OK(response, throw)
    return response

  def OK(self, response, throw=False):
    ok = response['stat'] == 'ok'
    if not ok and throw:
      raise Exception('ReviewBoard response stat not "ok"')
    return ok

  def Login(self, username=None, password=None):
    if username is None:
      username = self.username
    if password is None:
      password = self.password
    rb.Run('accounts/login', {'username': username, 'password': password})
    

if __name__ == '__main__':
  reviewers = ['larry', 'moe', 'curly']
  rb = ReviewBoard('10.100.120.86', 'username', 'password')
  rb.Login()
  response = rb.Run('reviewrequests/11/reviews')
  reviews = response['reviews']
  for review in reviews:
    reviewer = review['user']['username']
    ship_it = review['ship_it']
    if reviewer in reviewers and ship_it:
      print '"%s" SAYS SHIP IT!' % reviewer.upper()

Sign in to add a comment
Hosted by Google Code