Bugzilla:BzAPI

These pages document the HTTP REST API for Bugzilla.

Servers

The existing implementation of the API is a proxy which can be installed and pointed at any Bugzilla (version 3.4 or above). An installation of the latest version, pointed at https://bugzilla.mozilla.org/, can be found at:

https://api-dev.bugzilla.mozilla.org/0.1/

As the API is tweaked and revised, the version number in that URL will increase, so updates don't break every single client immediately. However, old versions are not guaranteed to persist. Authors of API-using tools are strongly encouraged to join the mailing list XXX.

Authentication

The API and the proxy support anonymous access as much as the target Bugzilla does. If you want to authenticate, pass:

username=fred@bedrock.com&password=ilovewilma

on any request. The above-mentioned instance of the API is available over HTTPS and accesses bugzilla.mozilla.org over HTTPS. XXXdisable_logging?

Data Formats

Currently, the API has only been tested with JSON. Although it's currently the default, you should set an "Accept: application/json" header on all calls. However, Catalyst::Controller::REST supports a number of serialization and deserialization formats, and can be extended for more. XML is next on the list to test with, but set "Accept: text/xml" and see what you get back :-) And then try feeding it back in again...

Errors

All of the "output" documentation below documents successful returns :-) Errors are of the following form:

{
  "error": True Boolean,
  "message": String,
  "xmlrpc_code": Integer, // optional; if underlying implementation is XML-RPC
  "http_code": Integer,   // optional; if Bugzilla returned a useful HTTP code
  "html_page": String     // optional; if underlying implementation is scraping and error is not recognised
}

The documentation gives a list of possible values for "message"; the list is almost certainly not exhaustive. Error handling is always a large part of any good API, and is one place where this one might be a little rough. In the future, ponies will provide each possible error object with a single unambiguous error code in a "code" field. The other codes are not guaranteed to be present, or continue to be present if they are there now. the html_page, in particular, is only there so you can read it manually for a better idea of what the error was, and ask for the API to support it properly.

Conflicts

There are two calls (bug/<id> PUT and attachment/<id> PUT) where you can set any field on that bug or attachment, and those calls always check for editing conflicts. All other calls which change things unconditionally make things as you request, and require no conflict resolution.

In the case of the two calls which check, conflict resolution must be implemented by the client. So if you call /bug/<id> PUT and the bug changed since your GET (i.e. the web interface would mid-air), you'll get an error, and your client will need to GET again, resolve the conflicts with the user using a UI of your choice, and attempt another PUT.

XXXinvestigate mid-airs

API Notes

• The <id> parameter for bugs must be a bug number for now; aliases may be added later.
• Flag support is spotty. Only those flags which are actually set, and not those which you could set, are returned. And to set a flag, you need to know the ID of the flag_type, which is not available through the API. At the moment, it's probably best to treat flags as read only.
• Groups are not yet supported. You may get some back on the GET calls (YMMV) but setting them is unlikely to work.
• Custom fields should work but multi-valued ones are not necessarily returned as arrays if there is 0 or 1 value. This is because I can't tell which custom fields are supposed to be multi-valued. As a hack, if your custom field name begins "cf_multi", it'll get array-ified.
• Not all time fields return timezone information. In this case, you will need to know the timezone of the Bugzilla you are accessing.
• Votes are not supported, and probably never will be.

API Calls: Bugs

Search for bugs (/bug GET)

Input

A) Search parameters, exactly as powerful as query.cgi but using the field names from the Bug object rather than those from the web interface (XXX_implement_cleanup!).

B) As above, with parameter count=1.

Output

A)

{ bugs: <arr> }

where "arr" is an array of [Bugzilla:REST_API:Objects#Bug|Bug].

B) Count of bugs:

{ "count": 136 }

Notes

• Only a subset of a bug's fields are returned on a search. These are those in bold on the [Bugzilla:REST_API:Objects#Bugs|list] (XXX_do_that).

Create new bug /bug POST

Input

[Bugzilla:REST_API:Objects#Bug|Bug] as POST body.

Output

201 Created status code, Location header pointing to new object.

{ "success": 1 }

XXX "ok instead of success?"?

Notes

• You can't add attachments with a new bug. Any attachment fields in the bug object will be ignored. Make a separate call.

Retrieve bug (/bug/<id> GET)

Input

• Bug ID on the URL
• Includes flags, CC list, related bugs and attachment metadata by default
• Does not include attachment data, comments or history - so amount of data is bounded
• attachmentdata=1, comments=1 and history=1 do the obvious things

Output

[Bugzilla:REST_API:Objects#Bug|Bug].

Update bug (/bug/<id> PUT)

Input

[Bugzilla:REST_API:Objects#Bug|Bug] as PUT body.

Output

{ "success": 1 }

Notes

• Groups are not yet supported
• You can't change the privacy flag on a comment

Errors

• This call always checks for conflicts and returns an error if there is one.

List attachments for bug (/bug/<id>/attachment GET)

Input

• Bug ID on the URL.
• attachmentdata=1 does the obvious thing (XXXcheck).

Output

{ attachments: <arr> }

where "arr" is an array of [Bugzilla:REST_API:Objects#Attachment|Attachment].

Notes

• No attachments -> empty array.

Create new attachment (/bug/<id>/attachment POST)

Input

[Bugzilla:REST_API:Objects#Attachment|Attachment] as POST body.

Output

201 Created status code, Location header pointing to new object.

{ "success": 1 }

Notes

• You can't set is_obsolete on a new attachment submission
• You can't set the same (multi-settable) flag twice on a single attachment submission

Retrieve attachment (/attachment/<id> GET)

Input

• Attachment ID on the URL.
• attachmentdata=1 does the obvious thing (XXXcheck).

Output

[Bugzilla:REST_API:Objects#Attachment|Attachment].

Update attachment metadata (/attachment/<id> PUT)

Input

[Bugzilla:REST_API:Objects#Attachment|Attachment] as PUT body.

Output

{ "success": 1 }

Notes

• You can't set the same (multi-settable) flag twice on a single attachment submission
• XXX Conflict checking?

List comments for bug (/bug/<id>/comment GET)

Input

• Bug ID on the URL
• "new_since" DateTime parameter (YYYYMMDDTHHMMSS) returns only ones since date given.

Output

{ comments: <arr> }

where "arr" is an array of [Bugzilla:REST_API:Objects#Comment|Comment].

Notes

• No comments (or none you can see) -> empty array. XXX_test

Add new comment to bug (/bug/<id>/comment POST)

Input

[Bugzilla:REST_API:Objects#Comment|Comment] as POST body.

Output

201 Created status code, Location header pointing to XXXwhere?.

{ "success": 1 }

Notes

• Unconditional - no conflict checking

List history for bug (/bug/<id>/history GET)

Input

• Bug ID on the URL.

Output

{ history: <arr> }

where "arr" is an array of [Bugzilla:REST_API:Objects#ChangeSet|ChangeSet].

API Calls: Users

Search for users (/user GET)

Errors

• returns list of users
• Query on ID, name or both; must be fast to support suggestions
• Implementation: XML-RPC API directly.

Retrieve user (/user/<id> GET)

Errors

• returns info about individual user
• 'id' can be user number or email address
• Implementation: XML-RPC API directly.