Personal tools

Bugzilla:REST API:Methods

From MozillaWiki

Revision as of 08:39, 2 February 2011 by Gerv (Talk | contribs)

Jump to: navigation, search

Contents

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

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

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 [Bugzilla:REST_API#Field_Control|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 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.

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

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

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

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

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

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

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