Bugzilla:BzAPI

These pages document the tip of the HTTP REST API for Bugzilla proxy software ("BzAPI"). Please file bugs (in either code or documentation) in the BzAPI component in bugzilla.mozilla.org.

Versions

Older pages in this wiki document released versions of BzAPI.

Version 0.1 (4th October 2009)

• Bugzilla:REST_API
• Bugzilla:Rest_API:Objects
• Bugzilla:Rest_API:Search

Version 0.2 (11th November 2009)

• Bugzilla:REST_API
• Bugzilla:Rest_API:Objects
• Bugzilla:Rest_API:Objects:Configuration
• Bugzilla:Rest_API:Search

Servers

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

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

Currently, bugzilla.mozilla.org runs an unmodified Bugzilla 3.2, and so quite a few capabilities of the API are not available (marked "3.4"). b.m.o. will soon be upgraded to 3.4, and there is a staging server at http://bugzilla-stage-tip.mozilla.org/. There is a version of the API, with full capabilities, pointed at this server:

https://api-dev.bugzilla.mozilla.org/stage/0.2/

It is suggested that this version is used for testing.

As the API is tweaked and revised, the version number in these URLs 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 mozilla.tools mailing list to be kept up to date.

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

as query parameters on any request. The above-mentioned instance of the API is available over HTTPS and accesses bugzilla.mozilla.org over HTTPS. Passwords are not logged on the API machine.

The cert on the API machine is signed by the Mozilla Root CA. Its MD5 fingerprint is 75:B2:EF:89:81:51:8F:99:13:DC:BF:44:47:0E:A9:8D.

Data Formats

On every request, you must set both Accept: and Content-Type: 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. The two do not have to be the same.

Currently, the API has only been tested with JSON. Although it's currently the default, if you are using JSON you should still 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... But the XML output format is very much not frozen.

Errors

All of the "output" documentation below documents successful returns :-) Calls may also return an Error.

The documentation below gives a list of possible values for the "message" field; 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.

API Notes

• Getting bug history and details of users will only work on the above API when bugzilla.mozilla.org is upgraded to Bugzilla 3.4 :-( Features that depend on 3.4 are marked "3.4".
• The <id> parameter for bugs must be a bug number for now; aliases will be supported later.
• Only bug time fields (creation/last_change) return timezone information. For the moment, for other time fields, you will need to know the timezone of the Bugzilla you are accessing.
• The added and removed fields of the Change object are always strings, even if the field_name is a multi-valued field and more than one value was added or removed. In that case, the values are comma-separated in the string. Parsing and auto-promotion would be possible, but has not yet been implemented.
• Votes are not supported.
• Examples are in JSON format because I had to pick one; see above regarding other formats.

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. (At the moment, it does also support the field names from the web interface, to make it easy to port URLs and other code across. But if supporting this becomes difficult, it might go away.)

B) As above, with parameter count=1.

Output

A)

{ "bugs": [ <array of 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 list. As a rule of thumb, only single-valued fields are returned.

Errors

Create new bug (/bug POST)

Input

Bug as POST body.

Output

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

{ "ref": "<same-as-location-header>" }

Notes

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

Errors

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 (history requires 3.4)
• Multi-valued custom fields are not, in general, 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 will get unconditionally array-ified. This limitation can only be lifted when the API is part of Bugzilla itself.

Output

Bug.

Notes

Errors

Update bug (/bug/<id> PUT)

Input

Bug as PUT body.

Output

{ "ok": 1 }

Notes

• You can only add one comment per call. Add a Comment object without an id to the comments array.
• This call does not support the updating of attachment metadata. Make a separate call to update attachments.
• Set assigned_to or qa_contact to the special value null (in JSON) to reset them to the default for the current component.
• You can update most fields singly, but some fields are coupled, and must be provided as a set (even if one has not changed), as follows:
  • 'status' and 'resolution'
  • 'blocks' and 'dependson'
  • 'component' and 'product'
  • 'version' and 'target_milestone' require 'product'

Errors

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

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

Input

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

Output

{ "comments": [ array of Comment ] }

In other words, a Bug with only the comment field.

Notes

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

Notes

Errors

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

Input

Comment as POST body.

Output

201 Created status code, Location header pointing to bug/<id>/comment (as individual comments don't have their own location).

{ "ref": "<same-as-location-header>" }

Notes

• Unconditional - no conflict checking

Errors

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

Input

• Bug ID on the URL.

Output

{ "history": [ array of ChangeSet ] }

In other words, a Bug with only the history field.

Notes

Errors

List flags for bug (/bug/<id>/flag GET)

Input

• Bug ID on the URL.

Output

{ "flags": [ array of Flag ] }

In other words, a Bug with only the flags field.

Notes

Errors

API Calls: Attachments

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

Input

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

Output

{ "attachments": [ array of Attachment ] }

In other words, a Bug with only the attachment field.

Notes

• No attachments -> empty array.

Errors

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

Input

Attachment as POST body.

Output

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

{ "ref": "<same-as-location-header>" }

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

Errors

Retrieve attachment (/attachment/<id> GET)

Input

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

Output

Attachment.

Notes

Errors

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

Input

Attachment as PUT body.

Output

{ "ok": 1 }

Notes

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

Errors

API Calls: Users

Search for users (/user GET) - 3.4

Input

• "match" parameter with string to match against either name or real_name.

Output

{ users: [ array of User ] }

Notes

• No matches -> empty array.

Errors

Retrieve user (/user/<id> GET) - 3.4

Input

User ID on the URL. Can be numeric ID or email address.

Output

User.

Notes

Errors

API Calls: Other

Configuration (/configuration GET) - needs template

This call requires the target Bugzilla to have a custom template dropped in to its template/en/custom directory. This is currently true of bugzilla-stage-tip but not of bugzilla.mozilla.org.

Input

• None

Output

Configuration

Notes

Errors