View source for Bugzilla:BzAPI:Methods

==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'''

[[Bugzilla:REST_API:Search|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 [[Bugzilla:REST_API:Objects#Bug|Bug]]> ] }


'''Notes'''

* Examples: [https://api-dev.bugzilla.mozilla.org/latest/bug?product=Bugzilla&priority=P1&severity=blocker all P1 blockers in the Bugzilla product], [https://api-dev.bugzilla.mozilla.org/latest/bug?changed_after=1h all bugs changed in the last hour]. 
* By default, the fields returned are those in bold on the [[Bugzilla:REST_API:Objects#Bug|Search page]]. You can use [[Bugzilla:REST_API#Field_Control|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'''

[[Bugzilla:REST_API:Search|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'''

* Examples: [https://api-dev.bugzilla.mozilla.org/latest/count?product=Bugzilla&priority=P1&severity=blocker number of P1s in the Bugzilla product], [https://api-dev.bugzilla.mozilla.org/latest/count?product=Bugzilla&priority=P1&x_axis_field=severity the same, broken down by severity], [https://api-dev.bugzilla.mozilla.org/latest/count?product=Bugzilla&priority=P1&x_axis_field=severity&y_axis_field=component 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'''

[[Bugzilla:REST_API:Objects#Bug|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 [[Bugzilla:REST_API:Objects#Comment|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'''

[[Bugzilla:REST_API:Objects#Bug|Bug]].

'''Notes'''

* Examples: [https://api-dev.bugzilla.mozilla.org/latest/bug/35 bug 35], [https://api-dev.bugzilla.mozilla.org/latest/bug/350001?include_fields=_default,comments,history,attachments.data bug 350001 with all comments, attachment data and history]. 
* If you want to retrieve multiple [[Bugzilla:REST_API:Objects#Bug|Bug]]s at once, use the Search interface and specify only Bug IDs as your search criteria. You will be returned full [[Bugzilla:REST_API:Objects#Bug|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'''

[[Bugzilla:REST_API:Objects#Bug|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 [[Bugzilla:REST_API:Objects#Comment|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 <tt>null</tt> (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 [[Bugzilla:REST_API:Objects#Comment|Comment]] ] }

In other words, a [[Bugzilla:REST_API:Objects#Bug|Bug]] with only the comment field.

'''Notes'''

* Example: [https://api-dev.bugzilla.mozilla.org/latest/bug/350001/comment bug 350001 comments].
* No comments (or none you can see) -> empty array.

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

'''Arguments'''

[[Bugzilla:REST_API:Objects#Comment|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 [[Bugzilla:REST_API:Objects#ChangeSet|ChangeSet]] ] }

In other words, a [[Bugzilla:REST_API:Objects#Bug|Bug]] with only the history field.

'''Notes'''

* Example: [https://api-dev.bugzilla.mozilla.org/latest/bug/350001/history 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 [[Bugzilla:REST_API:Objects#Flag|Flag]] ] }

In other words, a [[Bugzilla:REST_API:Objects#Bug|Bug]] with only the flags field.

'''Notes'''

* Example: [https://api-dev.bugzilla.mozilla.org/latest/bug/500004/flag 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 [[Bugzilla:REST_API:Objects#Attachment|Attachment]] ] }

In other words, a [[Bugzilla:REST_API:Objects#Bug|Bug]] with only the attachments field.

'''Notes'''

* Examples: [https://api-dev.bugzilla.mozilla.org/latest/bug/500004/attachment bug 500004 attachments], [https://api-dev.bugzilla.mozilla.org/latest/bug/350001/attachment?attachmentdata=1 bug 350001 attachments with data].
* No attachments -> empty array.

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

'''Arguments'''

[[Bugzilla:REST_API:Objects#Attachment|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'''

[[Bugzilla:REST_API:Objects#Attachment|Attachment]].

'''Notes'''

* Examples: [https://api-dev.bugzilla.mozilla.org/latest/attachment/235466?content-type=text/html attachment 235466], [https://api-dev.bugzilla.mozilla.org/latest/attachment/386129?attachmentdata=1 attachment 386129 with attachment data].

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

'''Arguments'''

[[Bugzilla:REST_API:Objects#Attachment|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 [[Bugzilla:REST_API:Objects#User|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'''

[[Bugzilla:REST_API:Objects#User|User]]. 

'''Notes'''

* Example: [https://api-dev.bugzilla.mozilla.org/latest/user/gerv@mozilla.org 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'''

[[Bugzilla:REST_API:Objects:Configuration|Configuration]]

'''Notes'''

* Example: [https://api-dev.bugzilla.mozilla.org/latest/configuration b.m.o. configuration].