MozillaWiki

Bugzilla:BzAPI:Objects: Difference between revisions

Bugzilla Discussion

Bugzilla:BzAPI:Objects (view source)

Revision as of 02:06, 21 September 2016

6,269 bytes added ,  21 September 2016
Add deprecation notice
(Add deprecation notice)
 
(53 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This page lists the objects used on the [[Bugzilla:REST_API]], and the fields of each, along with their types, descriptions, and any names those fields may have in other contexts.
<div style="border: thin dotted #aaa; padding:5px;">
'''This specific REST API, generally referred to as "BzAPI", is DEPRECATED. For new projects, use the [[Bugzilla:REST_API|native REST API]] instead. The BMO team has implemented a [[Bugzilla:BzAPI:CompatLayer|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.'''
</div><br>
 
This page lists the objects used on the [[Bugzilla:BzAPI]], and the fields of each, along with their types, descriptions, and any names those fields may have in other contexts.


====Notes====
====Notes====


* Fields marked Read Only are set automatically by Bugzilla, based on other information or fields. They may be returned by GET calls, but will be ignored in POST or PUT.
* A general API principle is that if you don't submit a field or object to a change function, it's unchanged. This means you can send simple changes without having to send the entire bug. However, due to limitations of Bugzilla, this does not work with attachments - you need to send the whole object.
* Fields marked Read Only are set automatically by Bugzilla, based on other information or fields. They may be returned by GET calls, but will be ignored in POST or PUT. (So you don't have to remove them before sending an object back.)
* Fields marked No Mod can be set when the object is created, but are Read Only thereafter.
* Fields marked No Mod can be set when the object is created, but are Read Only thereafter.
* Fields marked Optional may be missing entirely. Other fields are guaranteed to be present but may be blank. XXX_make_it_so.
* For the objects other than [[#Bug|Bug]], some fields are marked Optional to show that they are not always present. For a [[#Bug|Bug]], all fields should be considered Optional apart from "id" and "ref".
* For fields of type Boolean, "0", 0 and "" are false; everything else is true.  
* For fields of type Boolean, on submit, please use "1" and "0" for true and false. This may get relaxed later.
* Fields of type Timestamp are in YYYY-MM-DD HH:MM:SS format. XXX_is_this_the_best?
* Fields of type Timestamp should be sent and received in the UTC timezone in ISO 8601 format - YYYY-MM-DDTHH:MM:SSZ (T and Z being a literal "T" and "Z").


==Bug==
==Bug==
'''Bold''' means the field is in the default set returned on the search interface.


{| border="1"
{| border="1"
!Name!!Type!!Description!!Other Names
!Name!!Type!!Description!!Other Names
|- style="font-weight: bold"
|actual_time||Decimal, Read Only||Time it has taken to fix the bug so far||
|- style="font-weight: bold"
|alias||String||Bug's alias (text alternative to ID)||
|- style="font-weight: bold"
|assigned_to||[[#User|User]]||User responsible for the bug||
|-
|-
|actual_time||Decimal||Time it has taken to fix the bug so far||
|attachments||Array of [[#Attachment|Attachment]]||Related files stored by Bugzilla||attachment
|-
|- style="font-weight: bold"
|alias||String||Bug's alias (text alternative to number)||
|blocks||Array of Integer||IDs of bugs which can only be fixed after this one (note: only returned by default in Bugzilla > 4.4 or BMO 4.2)||blocked
|-
|assigned_to||User||User responsible for the bug||
|-
|attachment XXX_attachments||Array of Attachment||Related files stored by Bugzilla||
|-
|blocks||Array of Integer||IDs of bugs which can only be fixed after this one||
|-
|cc||Array of User||Users signed up to be notified of changes||
|-
|cc_accessible||Boolean||Whether CC list can see bug, regardless of groups||
|-
|-
|cc||Array of [[#User|User]]||Users signed up to be notified of changes||
|- style="font-weight: bold"
|classification||String||Name of classification (categorization above product)||
|classification||String||Name of classification (categorization above product)||
|-
|-
|comments||Array of Comment||Things people have said about the bug||long_desc
|comments||Array of [[#Comment|Comment]]||Things people have said about the bug||long_desc
|-
|- style="font-weight: bold"
|component||String||Bug's component (sub-product)||
|component||String||Bug's component (sub-product)||
|-
|- style="font-weight: bold"
|creation_time||Timestamp String, Read Only||When bug was filed||creation_ts, opendate
|creation_time||Timestamp String, Read Only||When bug was filed||creation_ts, opendate
|-
|- style="font-weight: bold"
|creator||[[#User|User]], Read Only||User who submitted the bug||reporter
|- style="font-weight: bold"
|deadline||Datestamp String||Date by which bug must be fixed||
|deadline||Datestamp String||Date by which bug must be fixed||
|- style="font-weight: bold"
|depends_on||Array of Integer||Bugs that must be fixed first  (note: only returned by default in Bugzilla > 4.4 or BMO 4.2)||dependson
|-
|-
|depends_on||Array of Integer||Bugs that must be fixed first||
|dupe_of||Integer||Bug number of which this bug is a duplicate (only present if bug is RESOLVED DUPLICATE)||
|- style="font-weight: bold"
|estimated_time||Decimal||Current estimated time for fix, in hours||
|-
|-
|estimated_time||Decimal||Total estimated time for fix, in hours||
|flags||Array of [[#Flag|Flag]]||Flags set on this bug||
|-
|-
|ever_confirmed||Boolean, Read Only||Whether bug has ever passed from UNCONFIRMED to CONFIRMED status||
|groups||Array of [[#Group|Group]]||Groups to which this bug belongs||
|-
|-
|flag XXXflags||Array of Flag||Flags set on this bug (XXXnote: not all possible flags)||
|history||Array of [[#ChangeSet|ChangeSet]], Read Only||Changes made to bug fields in the past (requires 3.4)||
|- style="font-weight: bold"
|id||Integer, Read Only||Unique numeric identifier for bug||bug_id
|-
|-
|history||Array of ChangeSet||Changes made to bug fields in the past||
|is_cc_accessible||Boolean||Whether CC list can see bug, regardless of groups||cclist_accessible
|-
|-
|id||Integer, Read Only||Unique reference for bug||bug_id
|is_confirmed||Boolean, Read Only||Whether bug has ever passed from UNCONFIRMED to CONFIRMED status||everconfirmed, is_everconfirmed
|-
|-
|is_creator_accessible||Boolean||Whether creator (reporter) can see bug, regardless of groups||reporter_accessible, is_reporter_accessible
|- style="font-weight: bold"
|keywords||Array of String||Tags (from a limited set) describing the bug||
|keywords||Array of String||Tags (from a limited set) describing the bug||
|-
|- style="font-weight: bold"
|last_change_time||Timestamp String, Read Only||Last change||delta_ts, changeddate
|last_change_time||Timestamp String, Read Only||Last change||delta_ts, changeddate
|-
|- style="font-weight: bold"
|op_sys||String||Operating system bug was seen on, e.g. Windows Vista, Linux||
|op_sys||String||Operating system bug was seen on, e.g. Windows Vista, Linux||
|-
|- style="font-weight: bold"
|platform||String||Computing platform bug was seen on, e.g. PC, Mac||rep_platform
|platform||String||Computing platform bug was seen on, e.g. PC, Mac||rep_platform
|-
|- style="font-weight: bold"
|priority||String||How important the bug is, e.g. P1, P5||
|priority||String||How important the bug is, e.g. P1, P5||
|-
|- style="font-weight: bold"
|product||String||Name of product||
|product||String||Name of product||
|-
|- style="font-weight: bold"
|qa_contact||User||User responsible for checking bug is fixed||
|qa_contact||[[#User|User]]||User responsible for checking bug is fixed||
|-
|- style="font-weight: bold"
|ref||String, Read Only||URL of bug in API||
|ref||String, Read Only||URL of bug in API||
|-
|- style="font-weight: bold"
|remaining_time||Decimal, Read Only||Hours left before fix will be done||
|remaining_time||Decimal, Read Only||Hours left before fix will be done||
|-
|- style="font-weight: bold"
|reporter||User, Read Only||User who submitted the bug||
|resolution||String||The resolution, if the bug is in a closed state, e.g. FIXED, DUPLICATE||
|-
|reporter_accessible||Boolean||Whether reporter can see bug, regardless of groups||
|-
|-
|see_also||Array of String||URLs of related bugs||
|see_also||Array of String||URLs of related bugs||
|-
|- style="font-weight: bold"
|severity||String||How severe the bug is, e.g. enhancement, critical||bug_severity
|severity||String||How severe the bug is, e.g. enhancement, critical||bug_severity
|-
|- style="font-weight: bold"
|status||String||Current status, e.g. NEW, RESOLVED||bug_status
|status||String||Current status, e.g. NEW, RESOLVED||bug_status
|-
|- style="font-weight: bold"
|summary||String||Short sentence describing the bug||short_desc
|summary||String||Short sentence describing the bug||short_desc
|-
|- style="font-weight: bold"
|target_milestone||String||When the bug is going to be fixed||
|target_milestone||String||When the bug is going to be fixed||
|-
|-
|token||String, Read Only||Token you'll need to submit to change the bug||
|update_token||String||Token you'll need to submit to change the bug; supplied only when logged in||token
|-
|- style="font-weight: bold"
|url||String||URL relating to the bug||bug_file_loc
|url||String||URL relating to the bug (in search defaults only on 4.0 and above)||bug_file_loc
|-
|- style="font-weight: bold"
|version||String||Version of software in which bug is seen||
|version||String||Version of software in which bug is seen||
|- style="font-weight: bold"
|whiteboard||String||Notes on current status||status_whiteboard
|-
|-
|whiteboard||String||Notes on current status||status_whiteboard
|work_time||Decimal (Submit Only)||Hours to be added to actual_time||
|}
|}
XXX_TODO_TOTEST groups
====Notes====


* Field values are configurable, so examples may not apply to your Bugzilla.
* Field values are configurable, so examples may not apply to your Bugzilla.
* 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.


==Comment==
==Comment==
Line 103: Line 115:
!Name!!Type!!Description!!Other Names
!Name!!Type!!Description!!Other Names
|-
|-
|author||User, Read Only||User who wrote the comment||
|attachment_id||Integer, Read Only||ID of attachment added at the same time as this comment, if any; 3.6 or above and /comment call only||
|-
|-
|bug_id||Integer, Read Only||ID of bug to which this is an attachment||
|attachment_ref||String, Read Only||Ref of attachment added at the same time as this comment, if any; 3.6 or above and /comment call only||
|-
|-
|bug_ref||String, Read Only||URL of associated bug in API||
|creator||[[#User|User]], Read Only||User who wrote the comment||
|-
|creation_time||Timestamp String, Read Only||Time comment was added||
|-
|-
|id||Integer, Read Only||Unique identifier of comment in Bugzilla||
|id||Integer, Read Only||Unique numeric identifier for comment; 3.4 or above (set by Bugzilla; must not be set when adding comments)||
|-
|-
|is_private||Boolean||Whether comment is private||
|is_private||Boolean||Whether comment is private||
|-
|-
|text||String, No Mod||Text of comment (plain text)||
|text||String, No Mod||Text of comment (plain text)||
|}
==Group==
{| border="1"
!Name!!Type!!Description!!Other Names
|-
|id||Integer||Unique numeric identifier for group (required on submit for 3.6 and below)||
|-
|name||String||Unique string identifier for group (required on submit for 4.0 and above)||
|}
Between 3.6 and 4.0, Bugzilla changed which of these two fields was considered "primary". Note that you should never have Bugzilla version problems if you always supply both fields on submit, and the two fields refer to the same group (i.e. no mismatches).
==Flag==
{| border="1"
!Name!!Type!!Description!!Other Names
|-
|id||Integer||Unique numeric identifier for this particular flag (set by Bugzilla; do not set when creating flags)||
|-
|name||String, Read Only||Descriptive non-unique name for flag type, e.g. 'review'||
|-
|requestee||[[#User|User]], Optional||User action is requested from, if flag is requestable; can only be set if setting status to '?'||
|-
|setter||[[#User|User]], Read Only||User who set the flag||
|-
|status||String||Flag value - '?', '+', '-' or 'X'||
|-
|type_id||Integer||Unique numeric identifier for flag type||
|}
* To remove a flag, pass it to an update function with a status of "X".
==ChangeSet==
{| border="1"
!Name!!Type!!Description!!Other Names
|-
|-
|time XXX_inconsistent?||Timestamp String, Read Only XXX_bad_format?||Time comment was added||
|changer||[[#User|User]]||Who made the changes||
|-
|changes||Array of [[#Change|Change]]||The changes made in one change submission||
|-
|change_time||Timestamp String||When the changes were made||
|}
|}


==User==
==Change==


{| border="1"
{| border="1"
!Name!!Type!!Description!!Other Names
!Name!!Type!!Description!!Other Names
|-
|-
|name||String||Email address of user XXX_not_always_true?||assignee, reporter, qa_contact (as flat fields)
|added||String||Values added, if any (comma-separated if multiple)||
|-
|-
|real_name||String, Read Only, Optional||User's real name||name, assignee_realname etc.
|field_name||String||Name of field changed||
|-
|-
|ref||String, Read Only||URL of user in API||
|removed||String||Values removed, if any (comma-separated if multiple)||
|}
|}
* The values of "added" and "removed" are flat strings, never objects. If multiple values are added or removed from a multi-valued field, the values are comma-separated. Users are represented by their login names.


==Attachment==
==Attachment==
Line 135: Line 193:
!Name!!Type!!Description!!Other Names
!Name!!Type!!Description!!Other Names
|-
|-
|attacher||User, Read Only||User who created attachment||
|attacher||[[#User|User]], Read Only||User who created attachment||
|-
|bug_id||Integer, Read Only||ID if bug to which this is an attachment||
|-
|-
|bug_id||Integer, Read Only||ID if bug to which this is an attachment XXX_unimplemented||
|bug_ref||String, Read Only||URL of associated bug in API||
|-
|-
|bug_ref||String, Read Only||URL of associated bug in API XXX_unimplemented||
|comments||Array of [[#Comment|Comment]], Optional, Submit Only||Bug comment associated with creation or change (only first element in array is looked at)||
|-
|-
|creation_time||Timestamp String, Read Only||When attachment was submitted||
|creation_time||Timestamp String, Read Only||When attachment was submitted||
|-
|-
|data||AttachmentData, No Mod||File data||
|data||String, Optional, No Mod||Attachment data encoded using encoding 'encoding'; provided only when attachmentdata requested||
|-
|-
|description||String||Text describing the attachment||
|description||String||Text describing the attachment||
|-
|-
|filename||String||Path-less filename of attachment||
|encoding||String, Optional, No Mod||Encoding of 'content'; 'base64' is the only supported value; provided only when attachmentdata requested||
|-
|-
|flag||Array of Flag||Flags set on this attachment (XXXnote: not all possible flags)||
|file_name||String||Path-less filename of attachment||
|-
|-
|id||Integer, Read Only||Unique reference for attachment||attach_id
|flags||Array of [[#Flag|Flag]]||Flags set on this attachment||
|-
|-
|is_obsolete||Boolean||Whether file is marked obsolete||isobsolete
|id||Integer, Read Only||Unique numeric identifier for attachment||attach_id
|-
|-
|is_patch||Boolean||Whether bug is a patch||ispatch
|is_obsolete||Boolean||Whether attachment is marked obsolete||isobsolete
|-
|-
|is_private||Boolean||Whether bug is private||isprivate
|is_patch||Boolean||Whether attachment is a patch||ispatch
|-
|is_private||Boolean||Whether attachment is private||isprivate
|-
|-
|ref||String, Read Only||URL of attachment in API||
|ref||String, Read Only||URL of attachment in API||
Line 163: Line 225:
|size||Integer||Size of attachment, in bytes||
|size||Integer||Size of attachment, in bytes||
|-
|-
|token||String||Token to submit to change attachment metadata||
|update_token||String, Optional||Token to submit to change attachment metadata; supplied only when logged in||token
|-
|-
|type||String||MIME type of attachment||
|content_type||String||MIME type of attachment||
|}
|}


==AttachmentData==
 
* Due to limitations in Bugzilla, when updating attachments (including their flags), you must post back the entire object, otherwise Bugzilla will complain about missing fields. This limitation may be removed in future.
 
==User==


{| border="1"
{| border="1"
!Name!!Type!!Description!!Other Names
!Name!!Type!!Description!!Other Names
|-
|-
|encoding||String, No Mod||Encoding of 'content'; 'base64' is only supported value||
|email||String||Email address of user (if you are logged in)||
|-
|-
|content||String, No Mod||Attachment data encoded using named method||
|id||Integer, Optional (for the moment)||Unique numeric identifier for user (currently only supplied on /user API)||
|-
|name||String||Email address of user (if you are logged in) or first part otherwise (which is therefore non-unique)||assignee, reporter, qa_contact (as flat fields)
|-
|real_name||String, Read Only, Optional||User's real name||name, assignee_realname etc.
|-
|ref||String, Read Only||URL of user in API||
|}
|}


==ChangeSet==
==Suggested Reviewer==


{| border="1"
{| border="1"
!Name!!Type!!Description!!Other Names
!Name!!Type!!Description!!Other Names
|-
|-
|changes||Array of Change||The changes made in one change submission||
|email||String||Email address of user (if you are logged in)||
|-
|id||Integer, Optional (for the moment)||Unique numeric identifier for user (currently only supplied on /user API)||
|-
|-
|when||Timestamp String XXX_XMLRPC_format||When the changes were made||
|name||String||User's real name||
|-
|-
|who||User||Who made the changes||
|review_count||Integer||Number of reviews in this user's queue.||
|}
|}


==Change==
==Error==


{| border="1"
{| border="1"
!Name!!Type!!Description!!Other Names
!Name!!Type!!Description!!Other Names
|-
|-
|added||String or Array XXX_promote?||Values added, if any||
|code||Integer, Read Only||Unambiguous definition of error (XXXunimplemented)||
|-
|-
|field_name||String||Field changed||
|error||Boolean (True), Read Only||Indicates the object is an error object||
|-
|-
|removed||String or Array XXX_promote?||Values removed, if any||
|html_page||String, Read Only, Optional||If underlying implementation is screen-scraping and if error is not recognised; only present so you can read it manually!||
|-
|http_code||Integer, Read Only, Optional||If Bugzilla returned a useful HTTP code||
|-
|message||String, Read Only||Short English string describing error||
|-
|xmlrpc_code||Integer, Read Only, Optional||If underlying implementation is XML-RPC||
|}
|}
* Error objects are distinguished from other objects because they have an "error" member set to a true value. You should test every API return to see if it is an [[#Error|Error]].
Mcote
Confirmed users
1,927

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/172251...1148495"