Jump to >

Overview of the Python API Client

Introduction

The API client provides convenient access to Review Board Web API resources, and makes performing REST operations simple. The API is accessed by instantiating the rbtools.api.client.RBClient class. Here is an example of how to instantiate the client, and retrieve the Root List Resource resource:

from rbtools.api.client import RBClient

client = RBClient('http://localhost:8080/')
root = client.get_root()

Accessing Resource Data

Accessing the fields contained in a resource payload is accomplished using attributes of the resource object. Each field in the payload under the resource’s main key will be accessed through an attribute of the same name. This also applies to fields contained within another field.

The following payload from the Server Info Resource will be used as an example.

{
  "info": {
    "capabilities": {
      "diffs": {
        "moved_files": true
      }
    },
    "product": {
      "is_release": true,
      "name": "Review Board",
      "package_version": "1.7beta1",
      "version": "1.7 beta 1"
    },
    "site": {
      "administrators": [
        {
          "email": "admin@example.com",
          "name": "Example Admin"
        }
      ],
      "time_zone": "UTC",
      "url": "http://example.com/"
    }
  },
  "stat": "ok"
}

To demonstrate how the data from this payload would be accessed, the following is a short example:

# Retrieve the info resource using the root resources
# info link.
info = root.get_info()

# Print the product version ("1.7 beta 1").
print info.product.version

# Print the only administrator's name ("Example Admin")
print info.site.administrators[0].name

Note

While using attributes is the preferred way of accessing fields on a resource, using the [] operator is also supported. The following would have also worked in the previous example:

info['product']['version']

Request Parameters

Some resources in the Web API allow query arguments to be passed with the request to alter what should be returned as the response. The supported request parameters are unique to each resource, and are listed on each resource’s documentation page.

Query arguments are added to a request by specifying keyword arguments when calling the method. A number of the request parameters use the ‘-‘ character, which should be replaced by an underscore when specified as a keyword argument (e.g. max-results would become max_results).

The following is an example which uses the counts-only and status request parameters on the Review Request List Resource, to get a count of pending review requests:

# Make a request for the list of pending review requests.
# Specify counts-only so only the number of results is returned.
requests = root.get_review_requests(counts_only=True, status="pending")

# Print the number of pending review requests
print requests.count

Resource Specific Details

The API provides additional functionality for a number of resources. Specific information can be found in Resource-Specific Functionality.