6.1.1. General

This is the standard REST API for external programs that want to interact with Bugzilla. It provides a REST interface to various Bugzilla functions.

6.1.1.1. Basic Information

Browsing

If the Accept header of a request is set to text/html (as it is by an ordinary web browser) then the API will return the JSON data as a HTML page which the browser can display. In other words, you can play with the API using just your browser to see results in a human-readable form. This is a good way to try out the various GET calls, even if you can’t use it for POST or PUT.

Data Format

The REST API only supports JSON input, and either JSON or JSONP output. So objects sent and received must be in JSON format.

On every request, you must set both the Accept and Content-Type HTTP headers to the MIME type of the data format you are using to communicate with the API. Content-Type tells the API how to interpret your request, and Accept tells it how you want your data back. Content-Type must be application/json. Accept can be either that, or application/javascript for JSONP. In the latter`case, add a callback parameter to name your callback.

Parameters may also be passed in as part of the query string for non-GET requests and will override any matching parameters in the request body.

Example request which returns the current version of Bugzilla:

GET /rest/version HTTP/1.1
Host: bugzilla.example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "version" : "4.2.9+"
}

Errors

When an error occurs over REST, an object is returned with the key error set to true.

The error contents look similar to:

{
  "error": true,
  "message": "Some message here",
  "code": 123
}

6.1.1.2. Common Data Types

The Bugzilla API uses the following various types of parameters:

type description
int Integer.
double A floating-point number.
string A string.
email A string representing an email address. This value, when returned, may be filtered based on if the user is logged in or not.
date A specific date. Example format: YYYY-MM-DD.
datetime A date/time. The timezone used will be that of the server, which is usually UTC. If you provide a timezone that doesn’t match the timezone on the server it will be ignored. Example format: YYYY-MM-DDTHH24:MI:SSZ.
boolean true or false.
base64 A base64-encoded string. This is the only way to transfer binary data via the API.
array An array. There may be mixed types in an array. [ and ] are used to represent the beginning and end of arrays.
object A mapping of keys to values. Called a “hash”, “dict”, or “map” in some other programming languages. The keys are strings, and the values can be any type. { and } are used to represent the beginning and end of objects.

Parameters that are required will be displayed in bold in the parameters table for each API method.

6.1.1.3. Authentication

Some methods do not require you to authenticate. An example of this is Get Bug. However, authenticating yourself allows you to see non-public information, for example, a bug that is not publicly visible.

The supported way to authenticate Red Hat Bugzilla is to use the Authorization header with an API Key. Authorization: Bearer YOURAPIKEY. Using this approach you do not login, you simply provide this header with every API call.

You can set up API keys by using the ‘API Key’ tab in the Preferences pages. It is worth adding a named key for different uses. This way if a key needs to be revoked, or banned, the impact can be limited to specific uses.

All other authentication mechanisms for API access are deprecated and will be removed in the near future.

6.1.1.4. Useful Parameters

Many calls take common arguments. These are documented below and linked from the individual calls where these parameters are used.

Including Fields

Many calls return an array of objects with various fields in the objects. (For example, Get Bug returns a list of bugs that have fields like id, summary, creation_time, etc.)

These parameters allow you to limit what fields are present in the objects, to improve performance or save some bandwidth.

include_fields: The (case-sensitive) names of fields in the response data. Only the fields specified in the object will be returned, the rest will not be included. Fields should be comma delimited.

Invalid field names are ignored.

Example request to Get User:

GET /rest/user/1?include_fields=id,name

would return something like:

{
  "users" : [
    {
      "id" : 1,
      "name" : "user@domain.com"
    }
  ]
}

Excluding Fields

exclude_fields: The (case-sensitive) names of fields in the return value. Thefields specified will not be included in the returned hashes. Fields should be comma delimited.

Invalid field names are ignored.

Specifying fields here overrides include_fields, so if you specify a field in both, it will be excluded, not included.

Example request to Get User:

GET /rest/user/1?exclude_fields=name

would return something like:

{
  "users" : [
    {
      "id" : 1,
      "real_name" : "John Smith"
    }
  ]
}

Some calls support specifying “subfields”. If a call states that it supports “subfield” restrictions, you can restrict what information is returned within the first field. For example, if you call Get Product with an include_fields of components.name, then only the component name would be returned (and nothing else). You can include the main field, and exclude a subfield.

There are several shortcut identifiers to ask for only certain groups of fields to be returned or excluded:

value description
_all All possible fields are returned if this is specified in include_fields.
_default Default fields are returned if include_fields is empty or this is specified. This is useful if you want the default fields in addition to a field that is not normally returned.
_extra Extra fields are not returned by default and need to be manually specified in include_fields either by exact field name, or adding _extra.
_custom Custom fields are normally returned by default unless this is added to exclude_fields. Also you can use it in include_fields if for example you want specific field names plus all custom fields. Custom fields are normally only relevant to bug objects.

This documentation undoubtedly has bugs; if you find some, please file them here.