Bugzilla:API Comparison

This page attempts to list the differences between the Bugzilla XML-RPC/JSON-RPC API (on the Bugzilla tip) and the BzAPI REST API (on the BzAPI tip). This will hopefully be useful data as we figure out how to align them, as Bugzilla implements a native REST API.

High Level

Matching Calls

• Search for bugs: /bug GET -- Bug.search
• Create new bug: /bug POST -- Bug.create
• Retrieve bug: /bug/<id> GET -- Bug.get
• Update bug: /bug/<id> PUT -- Bug.update / Bug.update_see_also / Bug.update_tags

• List comments for bug: /bug/<id>/comment GET -- Bug.comments
• Add new comment to bug: /bug/<id>/comment POST -- Bug.add_comment
• List history for bug: /bug/<id>/history GET -- Bug.history

• List attachments for bug: /bug/<id>/attachment GET -- Bug.attachments
• Retrieve attachment: /attachment/<id> GET -- Bug.attachments
• Create new attachment: /bug/<id>/attachment POST -- Bug.add_attachment

• Search for users: /user GET -- User.get
• Retrieve user: /user/<id> GET -- User.get

RPC Calls Supplying Subsets of REST /config Call

• Get current Bugzilla version: Bugzilla.version
• Get info about classifications by name or ID: Classification.get
• Get info about products: Product.get
• Get info about fields and their legal values: Bug.fields

RPC Calls Not In REST

User

• Get list of installed extensions: Bugzilla.extensions
• Get info about Bugzilla's notions of time: Bugzilla.time
• Get safe parameter values: Bugzilla.parameters
• Get the latest time from the audit_log table: Bugzilla.last_audit_time
• Get info about products a user can search on: Product.get_selectable_products
• Get info about products a user can enter bugs against: Product.get_enterable_products
• Get info about products a user can search or enter bugs against: Product.get_accessible_products

Admin

• Create a new group: Group.create
• Update info about a group: Group.update
• Create a new product: Product.create
• Update info about a product: Product.update
• Offer account by email: User.offer_account_by_email
• Create a user account: User.create
• Update a user account: User.update

Not Needed For REST

• Log in to RPC interface: User.login
• Log out of RPC interface: User.logout

Deprecated

• Bugzilla.timezone
• Bug.legal_values

REST Calls Not In RPC

• List flags for bug: /bug/<id>/flag GET (no specific call, although Bug.get returns the info)
• Count bugs: /count GET
• Update attachment metadata: /attachment/<id> PUT
• Get Configuration: /configuration GET (although some config stuff is available as more specific calls)

Matching Calls: Details

Search for bugs

• /bug GET -- Bug.search

Differences:

• The REST API gives you the full power of the HTML query interface. The RPC API is a simple ANDed exact match search, covering only a limited number of fields. This is the major difference.

The following differences are copied from the analysis of the call for returning a single bug.

• The REST API returns User objects instead of email addresses.
• The REST API does not return "creation_date" or "modification_date" on flags.
• The REST API returns Group objects (with name and ID) instead of group names.
• The REST API includes attachment metadata by default. The RPC API does not include any attachment data at all.
• The REST API includes comments if you ask for them using field control. The RPC API does not include comments.
• The REST API does not return the "is_open" field.
• The REST API returns a "ref" field.

Create new bug

• /bug POST -- Bug.create

The BzAPI call is backed by the RPC call, so they are quite similar.

Differences:

• The BzAPI call takes the initial description as a single member of the "comments" array rather than as a single-valued field called "description".
• The BzAPI call takes User objects rather than flat email addresses.
• The BzAPI call accepts any fields; it does a behind-the-scenes update for any fields not set in the initial Bug.create call. The RPC call only takes a limited set of fields.

Retrieve bug

• /bug/<id> GET -- Bug.get

Differences:

• The REST API returns only a single bug; the RPC API can return multiple bugs.
• The REST API does not support the experimental "permissive" boolean on requests.
• The time tracking fields are defined as double in RPC, and Decimal in REST.
• The REST API returns User objects instead of email addresses.
• The REST API does not return "creation_date" or "modification_date" on flags.
• The REST API returns Group objects (with name and ID) instead of group names.
• The REST API includes attachment metadata by default. The RPC API does not include any attachment data at all.
• The REST API includes comments if you ask for them using field control. The RPC API does not include comments.
• The REST API does not return the "is_open" field.
• The REST API returns a "ref" field.

Other than that, field name compatibility is very good.

Update bug

• /bug/<id> PUT -- Bug.update / Bug.update_see_also / Bug.update_tags

Differences:

• The REST API requires a valid "token" field.
• The REST API optionally does mid-air collision detection (by setting "last_change_time"). The RPC API does not.
• The REST API sends User objects instead of email addresses.
• The RPC API has an "add/remove/set" model (with "set" sometimes not implemented) for some multi-valued fields where the REST API simply has a "set" model. These are "blocks", "depends_on", "cc", "groups", "keywords" and "see_also".
• Adding comments via REST involves adding a hash to an array; in RPC, it's a simple hash (with "body" and "is_private" members).
• The RPC API has a mechanism for updating the privacy of existing comments - the comment_is_private hash. I'm not sure how the REST API handles that.
• The RPC API permits the setting of "remaining_time", which is Read Only in the REST API.
• The REST API uses the JSON "null" value to "reset to default" for assignee and QA contact, whereas the RPC API has special boolean fields "reset_assigned_to" and "reset_qa_contact".
• The RPC API returns much more info about the bug and the change than the REST API does.

List comments for bug

• /bug/<id>/comment GET -- Bug.comments

The BzAPI call is backed by the RPC call, so they are quite similar.

Differences:

• The BzAPI call only works for a single bug, as specified in the URL used. The RPC call works for multiple bugs.
• The RPC call can request comments by ID; the BzAPI does not have that ability.
• BzAPI returns User objects rather than bare email addresses
• BzAPI does not return the bug_id field for each comment
• BzAPI returns attachment_ref fields if there is an attachment_id
• BzAPI does not return the "count" field (for consistency; as it's new - code comment says "feel free to add it back when making native" :-)
• BzAPI does not return the (deprecated) "time" field; it returns "creation_time" (which RPC also returns).

Add new comment to bug

• /bug/<id>/comment POST -- Bug.add_comment

The BzAPI call is backed by the RPC call, so they are quite similar.

Differences:

• BzAPI does not support the "work_time" parameter.
• BzAPI return value includes a "ref" as well as an "id".

List history for bug

• /bug/<id>/history GET -- Bug.history

The BzAPI call is backed by the RPC call, so they are quite similar.

Differences:

• RPC "who" field is "changer" in BzAPI
• RPC "when" field is "change_time" in BzAPI
• The BzAPI call uses consistent, modern field names for the 'field_name' field on each history entry. I'm not sure what the RPC API does, but it may well use the traditional field names (e.g. "bug_status").
• The BzAPI call returns User objects rather than email addresses for the 'changer' field

List attachments for bug

• /bug/<id>/attachment GET -- Bug.attachments

Differences:

• The RPC API can take either a list of bug IDs or a list of attachment IDs, and returns different structures depending on which you give. This REST API takes a single bug ID only.
• The REST API returns "ref", "bug_ref", and "encoding" (only "base64" supported) fields which the RPC API does not.
• The REST API returns "description"; the RPC API also returns it, but is moving to call it "summary"
• The REST API returns "attacher"; the RPC API also returns it but is moving to call it "creator"
• The REST API does not have "creation_date" and "modification_date" for flags.
• The RPC API returns a "last_change_time"; the REST API does not.
• The REST API does not return attachment data by default.

Retrieve attachment

• /attachment/<id> GET -- Bug.attachments

Differences:

• The RPC API can take either a list of bug IDs or a list of attachment IDs, and returns different structures depending on which you give. This REST API takes a single attachment ID only.
• The REST API returns "ref", "bug_ref", and "encoding" (only "base64" supported) fields which the RPC API does not.
• The REST API returns "description"; the RPC API also returns it, but is moving to call it "summary"
• The REST API returns "attacher"; the RPC API also returns it but is moving to call it "creator"
• The REST API does not have "creation_date" and "modification_date" for flags.
• The RPC API returns a "last_change_time"; the REST API does not.
• The REST API does not return attachment data by default.

Create new attachment

• /bug/<id>/attachment POST -- Bug.add_attachment

Differences:

• The RPC API allows a single uploaded attachment to be added to multiple bugs at once. The REST API does not.
• The above also means the RPC API takes an "ids" array whereas the REST API takes a "bug_id" parameter.
• The REST API allows you to add a comment at the same time; the RPC API does not.
• The REST API uses "description"; RPC uses "summary".
• The REST API allows you to set flags on the attachment; the RPC API does not.

Search for users

• /user GET -- User.get

The BzAPI call is backed by the RPC call, so they are quite similar.

Differences:

• REST only supports search by name matching. RPC supports an exact name list, name matching, an ID list, and/or group.

Retrieve user

• /user/<id> GET -- User.get

The BzAPI call is backed by the RPC call, so they are quite similar.

Differences:

• REST supports retrieving individual users by ID or by name. RPC just has the general search call which can be made specific.

Configuration Calls: Details

BzAPI has a single call to get a large config data structure, whereas the RPC API is more fine-grained.

Get current Bugzilla version

• Bugzilla.version

Get info about classifications by name or ID

• Classification.get

Get info about products

• Product.get

Get info about fields and their legal values

• Bug.fields

RPC Calls Not In REST: Details

Get list of installed extensions

• Bugzilla.extensions

Example:

 {
   'extensions': {
      'ContributorEngagement': {
        'version': '2.0'
      },
      'SiteMapIndex': {
        'version': '1.0'
      },
      'ProductDashboard': {
        'version': '4.2.6'
      },
      'GuidedBugEntry': {
        'version': '1'
      },
      'Voting': {
        'version': '4.2.6+'
      },
      ...
   }
 }

REST Proposal:

GET /extensions

Get info about Bugzilla's notions of time

• Bugzilla.time

Example:

 {
   'db_time': '20130524T17:49:57',
   'web_time': '20130524T17:49:57',
   'tz_short_name': 'UTC',
   'tz_name': 'UTC',
   'web_time_utc': '20130524T17:49:57',
   'tz_offset': '+0000'
 }

REST Proposal:

GET /time

Get safe parameter values

• Bugzilla.parameters

Example:

 { 
   'parameters': {
     'ajax_user_autocompletion': '1',
     'allow_attachment_deletion': '0',
     'allow_attachment_display': '1',
     'allowbugdeletion': '0',
     'allowemailchange': '1',
     'allowuserdeletion': '0',
     ...
   }
 }

REST Proposal:

GET /parameters

Get the latest time from the audit_log table

• Bugzilla.last_audit_time

Example:

 {
   'last_audit_time': '20130325T01:07:23'
 }

REST Proposal:

GET /last_audit_time

Get info about products a user can search on

• Product.get_selectable_products

Example:

 {
   'ids': [
     '2',
     '3',
     '19',
     '1',
     '4'
   ]
 }

REST Proposal:

GET /product?type=selectable (default type = accessible)

Get info about products a user can enter bugs against

• Product.get_enterable_products

Example:

 {
   'ids': [
     '2',
     '3',
     '19',
     '1',
     '4'
   ]
 }

REST Proposal:

GET /product?type=enterable

Get info about products a user can search or enter bugs against

• Product.get_accessible_products

Example:

{
  'ids': [
    '2',
    '3',
    '19',
    '1',
    '4'
  ]
}

REST Proposal:

GET /product?type=accessible

Create a new group

• Group.create

Example:

Request:

 { 
   'name': 'test_group',
   'description': 'New Test Group',
   'user_regexp': '@mozilla\.com$',
   'is_active': '1'
 }

Response:

 {
   'id': '35'
 }

REST Proposal:

POST /group

Update info about a group

• Group.update

Example:

Request:

 { 
   'names': 'editbugs',
   'description': 'New description'
 }

Response:

 {
   'groups': [
     {
       'id': '15',
       'changes': {
         'description': {
           'added': 'New description',
           'removed': 'Old description'
         }
       }
     }
   ]
 }

REST Proposal:

PUT /group/15

Create a new product

• Product.create

Example:

Request:

 {
   'classification': 'Unclassified',
   'name': 'AnotherProduct4', 
   'description': 'This is another product', 
   'version': 'unspecified',
   'default_milestone': '1.0', 
   'create_series': '0', 
   'is_open': '0',
   'has_unconfirmed': '0' 
 }

Response:

 {
   'id': '45'
 }

REST Proposal:

POST /product

Update info about a product

• Product.update

Example:

Request:

 {
   'names': 'TestProduct',
   'description': 'This is an updated description'
 }

Response:

{
  'products': [
    {
      'id': '35',
      'changes': {
        'description': {
          'added': 'This is an updated description',
          'removed': 'Old description'
        }
      }
    }
  ]
}

REST Proposal:

PUT /product/35

Offer account by email

• User.offer_account_by_email

Example:

Request:

 {
   'email': 'dkl@mozilla.com'
 }

Response: None

REST Proposal:

POST /user/email

Create a user account

• User.create

Example:

Request:

 {
   'email': 'test@mozilla.com',
   'full_name': 'Test User',
   'password': 'password'
 }

Response:

 {
   'id': '12345'
 }

REST Proposal:

POST /user

Update a user account

• User.update

REST Calls Not In RPC: Details

List flags for bug

• /bug/<id>/flag GET

(no specific call, although Bug.get returns the info)

Count bugs

• /count GET

Update attachment metadata

• /attachment/<id> PUT

Get Configuration

• /configuration GET

(although some config stuff is available as more specific calls)

Missing Calls in REST and RPC

Get information about a group

• /group/15 GET

Meta Issues

Reviewing the "Matching Calls" section, it seems that the following issues come up more than once:

User vs email

REST uses User objects whereas RPC uses filtered email addresses depending on whether the user is logged in. The question here is whether the display name (and perhaps other info) about the user is sufficiently useful on a regular basis to be made part of the returned data. If it is, that would suggest moving to what REST does. If not, that would suggest moving towards what RPC does.

This is also an issue for Group objects vs. group names in the bug retrieval API.

Multiple values for a field

The RPC API has an add/remove/set model for updating fields with multiple values, such as "blocks", "depends_on", "cc", "groups", "keywords" and "see_also". The REST API has only a "set" model. This is an API design difference.

Config information

The REST API returns one single large config info JSON structure. The RPC API has a more fine-grained approach, and does not provide as much information even if you add it up from all the possible calls. This is an API design difference.

Error handling

The REST API returns various different flavors of error depending on the underlying implementation, whereas the RPC API simply returns an error code and description.

REST also makes use of http status codes to designate types of errors as well. RPC normally returns the same status code even in an error condition and the client checks the payload to see if an error occurred.

Scratchpad

• Need to check if there are differences in include_fields/exclude_fields handling -- see bug 540818