Bugzilla:BzAPI

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 long as and as much as the target Bugzilla does. If you want to authenticate, pass:

username=fred@example.com&password=ilovewilma

on the URL.

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 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 the client will need to GET again, resolve the conflicts with the user using a UI of their choice, and attempt another PUT.

Errors

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

{
  "error": <true value>,
  "message": "This is an error message",
  "xmlrpc_code": NNN, // optional; if underlying implementation is XML-RPC
  "http_code": NNN    // ditto, if Bugzilla returned a useful HTTP code
}

The documentation gives a list of possible values for "message"; the list is almost certainly not exhaustive.

API Notes

The <id> parameter for bugs must be a bug number for now; aliases may be added later.

API Calls: Bugs

Search for bugs

Call: /bug GET

Input: search parameters, very similar to query.cgi but with cleaned-up field names, plus column control parameters (XXX)

Example input

Output: list of bugs

Example output

Input: as above, with &count=1
Output: Count of bugs: { "count": 136 }

Errors:

Create new bug

Call: /bug POST
Input: bug object.
Output: { "success": 1 }

Retrieve bug (/bug/<id> GET)

Return single bug data
Includes flags, CC list, related bugs and attachment metadata
Can take parameters to add attachment data, comments and history
Implementation: Directly request bug as XML and reformat.

Update bug (/bug/<id> PUT)

Update bug
Can change any fields
Always checks for conflicts and returns an error if there are any
Implementation: direct process_bug.cgi submission.

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

Return list of all attachments on a bug
Implementation: from bug XML.

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

Add new attachment
Unconditional - no conflict checking
Implementation: direct attachment.cgi submission.

Retrieve attachment (/attachment/<id> GET)

Return attachment
Just metadata by default; can take a param to return the file data too
Metadata includes size so client can decide whether it wants the data
Implementation: from bug XML.

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

Update attachment metadata
Conflict checking
Implementation: direct attachment.cgi submission.

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

Return list of comments
Can take a "new_since" parameter to return only recent ones
Implementation: XML-RPC API.

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

Append comment
Unconditional - no conflict checking
Implementation: XML-RPC API.

Retrieve single comment (/bug/<id>/comment/<id> GET)

Return a single comment
XXX Do we need this?
Does the DB reference comments by number? If not, can we count?
Implementation: from bug XML.

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

Return bug history data
XXX Do we need a new_since parameter?
Implementation: XML-RPC API.

API Calls: Users

Search for users (/user GET)

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)

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