Bugzilla:BzAPI:Methods

This specific REST API, generally referred to as "BzAPI", is DEPRECATED. For new projects, use the native REST API instead. The BMO team has implemented a compatibility layer to help existing apps transition off BzAPI onto the native REST API. Please migrate existing BzAPI-based apps to the new compatibility-layer endpoint as soon as possible, as BzAPI will be shut off at some point in the future. Direct any questions to the BMO team.

The native REST API is available in Bugzilla 5.0 and up, and on bugzilla.mozilla.org. Although BzAPI is deprecated, it can be used with older Bugzilla installations (versions prior to 5.0) to provide a REST API.

Bugs

Search for bugs (/bug GET)

Arguments

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.)

Response

{ "bugs": [ <array of Bug> ] }

Notes

• Examples: all P1 blockers in the Bugzilla product, all bugs changed in the last hour.
• By default, the fields returned are those in bold on the Search page. You can use include_fields to get more, and if you specify "include_fields=_all", you will get everything. (This may take longer.)

Count bugs (/count GET)

Arguments

Search parameters, as above (except quicksearch - sorry), plus zero or more of x_axis_field, y_axis_field and z_axis_field.

Response

Counts of bugs, as a scalar, 1D, 2D or 3D array depending on how many axis_field parameters you specified.

{ "data": 136 }

{ "data": [136, 121, 0, 33] }

{ "data": [ [136, 121, 0, 33], [7, 14, 21, 28] ] }

{ "data": [ [ [136, 121], [0, 33] ], [ [7, 14], [21, 28] ] ] }

Notes

• Examples: number of P1s in the Bugzilla product, the same, broken down by severity, the same, broken down by severity and component.
• If you specify a z_axis_field without an x or a y, or a y without an x, the results are undefined. So don't do that.

Create new bug (/bug POST)

Arguments

Bug, or part thereof, as POST body. The following fields are always compulsory: product, component, summary and version. The following fields may be compulsory depending on the configuration of your Bugzilla: comments (single entry, as initial description), op_sys, platform, priority and severity.

Response

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

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

Notes

• The initial description is added using a comment object attached to the bug as the first item in the "comments" array. All that is required is the "text" member.
• 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)

Arguments

• 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 (use field control to get them)
• 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.

Response

Bug.

Notes

• Examples: bug 35, bug 350001 with all comments, attachment data and history.
• If you want to retrieve multiple Bugs at once, use the Search interface. That interface has a different (reduced) default set of fields, due to the Bugzilla call it uses on the back end. If it doesn't have the fields you want by default, specify include_fields=_all. This will behind the scenes fetch full Bug objects for you. For best performance, specify only bug IDs as your search criteria.

Update bug (/bug/<id> PUT)

Arguments

Bug, or part thereof, as PUT body.

Response

{ "ok": 1 }

Notes

• Updating a bug fails if you don't supply a value for 'token'. This is a security token used by the web interface to prevent people's browsers being exploited to make unwanted changes. To get this token, retrieve the bug data first.
• If you pass a last_change_time, this call will check for editing conflicts. If you do not, it will unconditionally update the bug to the state you send. If there is a conflict, conflict resolution must be implemented by the client re-GETting the resource, resolving the conflict and re-PUTting the resolved version.
• 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.
• To make this call check for conflicts, submit the last_change_time you received when getting the bug data. To make unconditional updates (be careful!) simply do not supply a last_change_time.
• 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 will return a "Mid-air collision" error if you submit a last_change_time earlier than the one Bugzilla has on record.

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

Arguments

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

Response

{ "comments": [ array of Comment ] }

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

Notes

• Example: bug 350001 comments.
• No comments (or none you can see) -> empty array.

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

Arguments

Comment as POST body.

Response

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

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

Arguments

• Bug ID on the URL.

Response

{ "history": [ array of ChangeSet ] }

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

Notes

• Example: bug 350001 history.
• This call requires Bugzilla 3.4 or above.

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

Arguments

• Bug ID on the URL.

Response

{ "flags": [ array of Flag ] }

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

Notes

• Example: bug 500004 flags.

Attachments

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

Arguments

• Bug ID on the URL.
• attachmentdata=1 does the obvious thing (it's a shorthand for "include_fields=_default,data,encoding").

Response

{ "attachments": [ array of Attachment ] }

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

Notes

• Examples: bug 500004 attachments, bug 350001 attachments with data.
• No attachments -> empty array.

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

Arguments

Attachment as POST body.

Response

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

Retrieve attachment (/attachment/<id> GET)

Arguments

• Attachment ID on the URL.
• attachmentdata=1 does the obvious thing (it's a shorthand for "include_fields=_default,data,encoding").

Response

Attachment.

Notes

• Examples: attachment 235466, attachment 386129 with attachment data.

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

Arguments

Attachment as PUT body.

Response

{ "ok": 1 }

Notes

• Updating an attachment fails if you don't supply a value for 'token'. This is a security token used by the web interface to prevent people's browsers being exploited to make unwanted changes. To get this token, retrieve the attachment data first.
• If you pass a last_change_time, this call will check for editing conflicts. If you do not, it will unconditionally update the bug to the state you send. If there is a conflict, conflict resolution must be implemented by the client re-GETting the resource, resolving the conflict and re-PUTting the resolved version.
• You can't set the same (multi-settable) flag twice on a single attachment submission
• To make this call check for conflicts, submit the last_change_time you received when getting the attachment data. To make unconditional updates (be careful!) simply do not supply a last_change_time.

Users

Search for users (/user GET)

Arguments

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

Response

{ users: [ array of User ] }

Notes

• Examples: not possible as this API requires the user to be logged in.
• No matches -> empty array.
• This call requires Bugzilla 3.4 or above.
• In Bugzilla 4.0 and above, only enabled (non-disabled) users will be returned. A later release of BzAPI will have a way of asking for results which include disabled users.

Retrieve user (/user/<id> GET)

Arguments

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

Response

User.

Notes

• Example: user 'gerv@mozilla.org'.
• This call requires Bugzilla 3.4 or above.

Other

Configuration (/configuration GET)

Arguments

• The flags=0 parameter removes flag-related information from the config; because flags can be enabled or disabled per-component, there is a lot of flag-related info and so this cuts down the size significantly. However, you will not be able to add new flags to bugs or attachments without this info.
• The cached_ok=1 parameter allows BzAPI to return cached data. BzAPI caches the output every time someone calls /configuration (or the noflags variant) and will pass the data back to you without contacting Bugzilla if you say that it's OK to send cached data. If the data was returned from the cache (which is not guaranteed), the JSON hash will have a "last_updated" value which is a unix time_t defining when the data was refreshed. It's your responsibility to see if that's recent enough and, if not, call the call again without "cached_ok=1".

Response

Configuration

Notes

• Example: b.m.o. configuration.