Confirmed users
1,927
edits
Bugzilla:BzAPI:Methods: Difference between revisions
Clarified note; updated links
m (Fix link to BzAPI) |
(Clarified note; updated links) |
||
| Line 1: | Line 1: | ||
==Notes== | ==Notes== | ||
* IMPORTANT: This page refers to the | * IMPORTANT: This page refers to the [[Bugzilla:BzAPI|BzAPI methods]]; if you are using bugzilla.mozilla.org, you should use the new native [[Bugzilla:REST_API|REST_API]]. | ||
==Bugs== | ==Bugs== | ||
| Line 9: | Line 9: | ||
'''Arguments''' | '''Arguments''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI: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''' | '''Response''' | ||
{ "bugs": [ <array of [[Bugzilla: | { "bugs": [ <array of [[Bugzilla:BzAPI:Objects#Bug|Bug]]> ] } | ||
| Line 19: | Line 19: | ||
* 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]. | * 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: | * By default, the fields returned are those in bold on the [[Bugzilla:BzAPI:Objects#Bug|Search page]]. You can use [[Bugzilla:BzAPI#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) === | === Count bugs (/count GET) === | ||
| Line 25: | Line 25: | ||
'''Arguments''' | '''Arguments''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI:Search|Search parameters]], as above (except quicksearch - sorry), plus zero or more of '''x_axis_field''', '''y_axis_field''' and '''z_axis_field'''. | ||
'''Response''' | '''Response''' | ||
| Line 48: | Line 48: | ||
'''Arguments''' | '''Arguments''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI: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''' | '''Response''' | ||
| Line 58: | Line 58: | ||
'''Notes''' | '''Notes''' | ||
* The initial description is added using a [[Bugzilla: | * The initial description is added using a [[Bugzilla:BzAPI: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. | * You can't add attachments with a new bug. Any attachment fields in the bug object will be ignored. Make a separate call. | ||
| Line 67: | Line 67: | ||
* Bug ID on the URL | * Bug ID on the URL | ||
* Includes flags, CC list, related bugs and attachment metadata by default | * 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 [https://wiki.mozilla.org/index.php?title=Bugzilla: | * Does not include attachment data, comments or history - so amount of data is bounded (use [https://wiki.mozilla.org/index.php?title=Bugzilla:BzAPI#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. | * 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''' | '''Response''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI:Objects#Bug|Bug]]. | ||
'''Notes''' | '''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]. | * 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: | * If you want to retrieve multiple [[Bugzilla:BzAPI:Objects#Bug|Bug]]s 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 <tt>include_fields=_all</tt>. This will behind the scenes fetch full [[Bugzilla:BzAPI:Objects#Bug|Bug]] objects for you. For best performance, specify only bug IDs as your search criteria. | ||
=== Update bug (/bug/<id> PUT) === | === Update bug (/bug/<id> PUT) === | ||
| Line 83: | Line 83: | ||
'''Arguments''' | '''Arguments''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI:Objects#Bug|Bug]], or part thereof, as PUT body. | ||
'''Response''' | '''Response''' | ||
| Line 93: | Line 93: | ||
* '''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. | * '''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. | * 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: | * You can only add one comment per call. Add a [[Bugzilla:BzAPI: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. | * 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. | * 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. | ||
| Line 116: | Line 116: | ||
'''Response''' | '''Response''' | ||
{ "comments": [ array of [[Bugzilla: | { "comments": [ array of [[Bugzilla:BzAPI:Objects#Comment|Comment]] ] } | ||
In other words, a [[Bugzilla: | In other words, a [[Bugzilla:BzAPI:Objects#Bug|Bug]] with only the comment field. | ||
'''Notes''' | '''Notes''' | ||
| Line 129: | Line 129: | ||
'''Arguments''' | '''Arguments''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI:Objects#Comment|Comment]] as POST body. | ||
'''Response''' | '''Response''' | ||
| Line 149: | Line 149: | ||
'''Response''' | '''Response''' | ||
{ "history": [ array of [[Bugzilla: | { "history": [ array of [[Bugzilla:BzAPI:Objects#ChangeSet|ChangeSet]] ] } | ||
In other words, a [[Bugzilla: | In other words, a [[Bugzilla:BzAPI:Objects#Bug|Bug]] with only the history field. | ||
'''Notes''' | '''Notes''' | ||
| Line 166: | Line 166: | ||
'''Response''' | '''Response''' | ||
{ "flags": [ array of [[Bugzilla: | { "flags": [ array of [[Bugzilla:BzAPI:Objects#Flag|Flag]] ] } | ||
In other words, a [[Bugzilla: | In other words, a [[Bugzilla:BzAPI:Objects#Bug|Bug]] with only the flags field. | ||
'''Notes''' | '''Notes''' | ||
| Line 185: | Line 185: | ||
'''Response''' | '''Response''' | ||
{ "attachments": [ array of [[Bugzilla: | { "attachments": [ array of [[Bugzilla:BzAPI:Objects#Attachment|Attachment]] ] } | ||
In other words, a [[Bugzilla: | In other words, a [[Bugzilla:BzAPI:Objects#Bug|Bug]] with only the attachments field. | ||
'''Notes''' | '''Notes''' | ||
| Line 198: | Line 198: | ||
'''Arguments''' | '''Arguments''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI:Objects#Attachment|Attachment]] as POST body. | ||
'''Response''' | '''Response''' | ||
| Line 220: | Line 220: | ||
'''Response''' | '''Response''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI:Objects#Attachment|Attachment]]. | ||
'''Notes''' | '''Notes''' | ||
| Line 230: | Line 230: | ||
'''Arguments''' | '''Arguments''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI:Objects#Attachment|Attachment]] as PUT body. | ||
'''Response''' | '''Response''' | ||
| Line 253: | Line 253: | ||
'''Response''' | '''Response''' | ||
{ users: [ array of [[Bugzilla: | { users: [ array of [[Bugzilla:BzAPI:Objects#User|User]] ] } | ||
'''Notes''' | '''Notes''' | ||
| Line 270: | Line 270: | ||
'''Response''' | '''Response''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI:Objects#User|User]]. | ||
'''Notes''' | '''Notes''' | ||
| Line 288: | Line 288: | ||
'''Response''' | '''Response''' | ||
[[Bugzilla: | [[Bugzilla:BzAPI:Objects:Configuration|Configuration]] | ||
'''Notes''' | '''Notes''' | ||
* Example: [https://api-dev.bugzilla.mozilla.org/latest/configuration b.m.o. configuration]. | * Example: [https://api-dev.bugzilla.mozilla.org/latest/configuration b.m.o. configuration]. | ||