Beanstalk

Code Review Resource

This resource represents Code Review processes requested for branches by users. Each Code Review belongs to two branches: a branch that’s being reviewed (target_branch) and a base branch to which the target_branch should be compared to (source_branch).

Each repository can have many Code Review processes associated with it. There can only be one Code Review for a specific target/source branch pair. Any user with at least read access to a repository can request a review for any branch.

Related resources

We split Code Review API into multiple resources to make it easier to use. Below is a list of all related resources. When I refer to a “sub-page” I mean sub-pages from the Code Review page inside the app.

  1. Comment: comments from Discussion sub-page.
  2. Issue: issues from Issues sub-page.
  3. Event: events from History sub-page.
  4. Assignee: users that are responsible for approving Code Reviews.
  5. Watcher: users that receive email notifications about Code Review’s Events.
  6. Settings: repository-wide settings that allow you to adjust your code review workflow.
  7. ReviewedCommit: ability to get review status and mark individual commits as approved/unapproved.

New format

We are gradually phasing out XML support from our API and this is one of the first resources that are provided only in JSON format. The format was also a bit adjusted compared to other resources: associated objects (like repositories and users) are now embedded into JSON itself, and there are no JSON root elements anymore.

Readable attributes

id integer Code Review ID.
description string Description of the branch provided by user. Optional.
target_branch string Name of the branch that’s being reviewed.
source_branch string Name of the branch to which target_branch should be compared to.
merge boolean True if user who requested the review wanted target_branch to be merged into source_branch when review is approved.
state string Current state of the Code Review. Can be: new, reopened, approved, cancelled.
available_transitions array List of states to which the Code Review can be transitioned.
comments_count integer Number of comments inside the Code Review.
events_count integer Number of events inside the Code Review.
updated_at datetime Timestamp that gets updated every time something changes inside the Code Review.
created_at datetime Date and time of when the Code Review has been requested.
repository hash Embedded Repository object.
id integer Repository ID.
name string Repository name (part of the Repository URL).
title string Repository title.
color string Repository color label.
requesting_user hash Embedded User object that requested the Code Review.
id integer User ID.
name string User full name.
login string User login.
email string User email address.
assigned_users array Array of embedded Users that were assigned to the Code Review.
id integer User ID.
name string User full name.
login string User login.
email string User email address.
assigned_at datetime Date and time when the User has been assigned to the Code Review.
approved_at datetime Date and time when the User has approved the Code Review.

Find All Code Reviews

Returns an array of Code Review process for all branches of all repositories in your account (to which you have access). To find reviews for a specific repository look below.

Optional GET parameters:

  • page (integer) — page number for pagination.
  • per_page (integer) — number of code reviews per page (default 25, maximum 100);
  • order_field (string) — name of the column that should be used for sorting. Can be: created_at, updated_at, comments_count, events_count (default is created_at);
  • order (string) — order direction. Should be either ASC or DESC (default is DESC);
  • state (string) — Only return reviews in a certain state. Can be: approved, cancelled, new, reopened, pending (pending is new and reopened combined);
  • creator (integer) — Only return reviews that were created by a specific User;
  • assignee (integer) — Only return reviews that are assigned to a specific User.
json http-request 
GET /api/code_reviews.json

Click to expand…

json http-response 
{
  "page": 1,
  "per_page": 25,
  "total_pages": 1,
  "page_entries": 5,
  "total_entries": 5,
  "code_reviews": [
    {
      "id": 5,
      "description": "",
      "source_branch": "master",
      "target_branch": "feature-5",
      "merge": true,
      "state": "reopened",
      "available_transitions": [
        "approve",
        "cancel"
      ],
      "comments_count": 13,
      "events_count": 40,
      "updated_at": "2014/12/31 10:37:24 -0500",
      "created_at": "2014/11/18 16:22:57 -0500",
      "repository": {
        "id": 12,
        "name": "git-repo",
        "title": "git-repo",
        "color": "red-orange"
      },
      "requesting_user": {
        "id": 1,
        "name": "Ilya Sabanin",
        "login": "ilya",
        "email": "ilya@example.com"
      },
      "assigned_users": []
    }
  ]
}

Find All Code Reviews for Repository

Returns an array of Code Review processes for all branches within a specified repository. Same GET parameters apply to this method as to the one above.

json http-request 
GET /api/{REPOSITORY_ID}/code_reviews.json

Click to expand…

json http-response 
{
  "page": 1,
  "per_page": 25,
  "total_pages": 1,
  "page_entries": 5,
  "total_entries": 5,
  "code_reviews": [
    {
      "id": 5,
      "description": "",
      "source_branch": "master",
      "target_branch": "feature-5",
      "merge": true,
      "state": "reopened",
      "available_transitions": [
        "approve",
        "cancel"
      ],
      "comments_count": 13,
      "events_count": 40,
      "updated_at": "2014/12/31 10:37:24 -0500",
      "created_at": "2014/11/18 16:22:57 -0500",
      "requesting_user": {
        "id": 1,
        "name": "Ilya Sabanin",
        "login": "ilya",
        "email": "ilya@example.com"
      },
      "assigned_users": []
    }
  ]
}

Find Code Review by ID

json http-request 
GET /api/{REPOSITORY_ID}/code_reviews/{REVIEW_ID}.json

Click to expand…

json http-response 
{
  "id": 5,
  "description": "",
  "source_branch": "master",
  "target_branch": "feature-5",
  "merge": true,
  "state": "reopened",
  "available_transitions": [
    "approve",
    "cancel"
  ],
  "comments_count": 13,
  "events_count": 37,
  "updated_at": "2014/12/31 09:47:03 -0500",
  "created_at": "2014/11/18 16:22:57 -0500",
  "requesting_user": {
    "id": 1,
    "name": "Ilya Sabanin",
    "login": "ilya",
    "email": "ilya@example.com"
  },
  "assigned_users": []
}

Find Code Review by Branch Name

Use this endpoint to find Code Review for a specific branch if you don’t know its ID. source_branch parameter is Code Review’s base branch (usually master or trunk) and target_branch is the branch being reviewed.

json http-request 
GET /api/{REPOSITORY_ID}/code_reviews/for_branches.json?source_branch={SOURCE_BRANCH}&target_branch={TARGET_BRANCH}.json

Click to expand…

json http-response 
{
  "id": 5,
  "description": "",
  "source_branch": "master",
  "target_branch": "feature-5",
  "merge": true,
  "state": "reopened",
  "available_transitions": [
    "approve",
    "cancel"
  ],
  "comments_count": 13,
  "events_count": 37,
  "updated_at": "2014/12/31 09:47:03 -0500",
  "created_at": "2014/11/18 16:22:57 -0500",
  "requesting_user": {
    "id": 1,
    "name": "Ilya Sabanin",
    "login": "ilya",
    "email": "ilya@example.com"
  },
  "assigned_users": []
}

Create Code Review

This action is essentially the same as clicking the “Request review” button in the app.

Writable attributes:

description string Description of the target_branch. Optional.
target_branch string Name of the branch that’s being reviewed.
source_branch string Name of the branch to which target_branch should be compared to.
merge boolean Merge branches when review gets approved. False by default.
assignee_ids array of integers IDs of Users that should be assigned to the review. Optional.
watchers_user_ids array of integers IDs of Users that should be added as watchers. Optional.
watchers_team_ids array of integers IDs of Teams that should be added as watchers. Optional.
json http-request 
POST /api/{REPOSITORY_ID}/code_reviews.json

{
  "code_review": {
    "source_branch": "master",
    "target_branch": "feature-6"
  }
}

Click to expand…

json http-response 
STATUS: 201

{
  "id": 6,
  "description": "",
  "source_branch": "master",
  "target_branch": "feature-6",
  "merge": false,
  "state": "new",
  "available_transitions": [
    "approve",
    "cancel"
  ],
  "comments_count": 0,
  "events_count": 0,
  "updated_at": "2014/12/31 09:47:03 -0500",
  "created_at": "2014/11/18 16:22:57 -0500",
  "requesting_user": {
    "id": 1,
    "name": "Ilya Sabanin",
    "login": "ilya",
    "email": "ilya@example.com"
  },
  "assigned_users": []
}

Update Code Review

This method can be used only to update description and merge attributes. Check methods below if you want to change Code Review’s state.

Writable attributes:

description string Description of the target_branch.
merge boolean Merge branches when review gets approved.
json http-request 
PUT /api/{REPOSITORY_ID}/code_reviews/{REVIEW_ID}.json

{
  "code_review": {
    "description": "New description"
  }
}

Click to expand…

json http-response 
STATUS: 200

{
  "id": 6,
  "description": "New description",
  "source_branch": "master",
  "target_branch": "feature-6",
  "merge": false,
  "state": "new",
  "available_transitions": [
    "approve",
    "cancel"
  ],
  "comments_count": 0,
  "events_count": 0,
  "updated_at": "2014/12/31 09:47:03 -0500",
  "created_at": "2014/11/18 16:22:57 -0500",
  "requesting_user": {
    "id": 1,
    "name": "Ilya Sabanin",
    "login": "ilya",
    "email": "ilya@example.com"
  },
  "assigned_users": []
}

Approve Code Review

Only code review assignees are authorized to call this method. Only new and reopened code reviews can be approved.

json http-request 
PUT /api/{REPOSITORY_ID}/code_reviews/{REVIEW_ID}/approve.json

Click to expand…

json http-response 
STATUS: 200

{
  "old_state": "new",
  "new_state": "approved",
  "merge": false,
  "available_transitions": [
    "reopen"
  ],
  "assigned_users": [
    {
      "id": 1,
      "name": "Ilya Sabanin",
      "login": "ilya",
      "email": "ilya@example.com",
      "assigned_at": "2014/12/31 13:19:12 -0500",
      "approved_at": null
    }
  ]
}

Cancel Code Review

Cancel a code review if you want to abandon the review process for any reason but keep the paper trail behind. Cancelled reviews can be later found and previewed. If you want to completely get rid of a code review use the Delete method below.

A code review assignee, a user who requested the review, or an account admin/owner are authorized to call this method. Only new and reopened reviews can be cancelled.

json http-request 
PUT /api/{REPOSITORY_ID}/code_reviews/{REVIEW_ID}/cancel.json

Click to expand…

json http-response 
STATUS: 200

{
  "old_state": "new",
  "new_state": "cancelled",
  "available_transitions": [
    "reopen"
  ]
}

Reopen Code Review

Reopen a previously approved or cancelled code review. After it has been reopened the review is basically treated as it was just created.

A code review assignee, a user who requested the review, or an account admin/owner are authorized to call this method.

json http-request 
PUT /api/{REPOSITORY_ID}/code_reviews/{REVIEW_ID}/reopen.json

Click to expand…

json http-response 
STATUS: 200

{
  "old_state": "cancelled",
  "new_state": "reopened",
  "available_transitions": [
    "approve",
    "cancel"
  ]
}

Delete Code Review

Permanently delete all information related to a particular Code Review process. Calling this will remove all Comments, Issues and Events associated with the Code Review.

json http-request 
DELETE /api/{REPOSITORY_ID}/code_reviews/{REVIEW_ID}.json

Click to expand…

json http-response 
HEAD 200 OK