Bugzilla:BzAPI:Methods

From MozillaWiki
Revision as of 03:08, 17 December 2009 by Gerv (talk | contribs)
Jump to navigation Jump to search

Notes

  • All times are supplied as UTC, in the ISO 8601 extended format (e.g. "2009-06-21T12:34:56Z"). This should define the time unambiguously, and should be widely and easily parseable, at the expense of probably not being directly displayable without a little manipulation.
  • Votes are not supported.

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

Errors

Count bugs (/count GET)

Arguments

Search parameters, as above, 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

Errors

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: 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

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

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

Response

Bug.

Notes

  • Examples: bug 35, bug 350001 with all comments, attachments and history.
  • If you want to retrieve multiple Bugs at once, use the Search interface and specify only Bug IDs as your search criteria. You will be returned full Bug objects instead of the reduced number of fields normally presented on a Search. This is a shortcut to avoid people having to make 20 calls to get 20 full bug objects.

Errors

Update bug (/bug/<id> PUT)

Arguments

Bug, or part thereof, as PUT body.

Response 

{ "ok": 1 }

Notes

  • 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

Notes

Errors

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

Errors


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

Errors

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

Errors

Attachments

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

Arguments

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

Response 

{ "attachments": [ array of Attachment ] }

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

Notes

Errors

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

Errors

Retrieve attachment (/attachment/<id> GET)

Arguments

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

Response

Attachment.

Notes

Errors

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

Arguments

Attachment as PUT body.

Response 

{ "ok": 1 }

Notes

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

Errors

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.

Errors

Retrieve user (/user/<id> GET)

Arguments

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

Response

User.

Notes

Errors

Other

Configuration (/configuration GET)

Arguments

  • None

Response 

Configuration

Notes

  • Example: b.m.o. configuration.
  • 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.

Errors

Retrieved from "https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI:Methods&oldid=189985"