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). The new native REST API is based very closely on the older RPC APIs.

Please note that clients currently using BzAPI should migrate to BMO's native BzAPI compatibility layer.

High Level

Matching Calls

Function	BzAPI	RPC
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 BzAPI /config Call

Function	RPC
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 BzAPI

User

Function	RPC
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

Function	RPC
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 BzAPI

Function	RPC
Log in to RPC interface	User.login
Log out of RPC interface	User.logout

Deprecated

RPC
Bugzilla.timezone
Bug.legal_values

BzAPI Calls Not In RPC

Function	BzAPI
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:

• BzAPI 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.

• BzAPI by default only returns those fields which can be returned by a Bugzilla search; the RPC returns a lot more fields by default. BzAPI can return the others, but it does an extra request under the covers.
• BzAPI returns User objects instead of email addresses.
• BzAPI does not return "creation_date" or "modification_date" on flags.
• BzAPI returns Group objects (with name and ID) instead of group names.
• BzAPI includes attachment metadata by default. The RPC API does not include any attachment data at all.
• BzAPI includes comments if you ask for them using field control. The RPC API does not include comments.
• BzAPI does not return the "is_open" field.
• BzAPI returns a "ref" field.

REST Unification Proposal: The semantics here are very different. I'm sure the Bugzilla team would like the RPC API to be a full search solution. So I propose that we do not implement this call in NATREST until we can implement it with full power, using the REST semantics - either separately or on top of full-power RPC. If we implement it on top of the current RPC implementation and then change it later, that will be a very big change from the current capabilities to the RPC ones, and then another very big change back later when we acquire full capabilities again. And when we implement it, we should make it return the full set of fields by default, not the limited set supported by the (default of the) current REST interface.

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.

REST Unification Proposal: We should either expand the RPC call to take a full set of fields, or do the same thing inside the NATREST call that we do now - do an extra call internally to set additional fields. Implementing only the limited set of fields is bound to cause compatibility issues for current REST API users. We could support both methods of setting the initial comment; doing it in the comments array is more REST-y, so we should document that way for REST.

Retrieve bug

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

Differences:

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

Other than that, field name compatibility is very good.

REST Unification Proposal: /search is the appropriate way to get multiple bugs in the REST world - the search allows you to search by ID. (Perhaps this is not so for RPC because the /search call is limited?) If we stick with a single bug here, that avoids the "permissive" issue and the need for a separate "faults" field. The rest of the differences can be resolved without compatibility issues by adding fields to whichever side lacks them. Although there's no point adding the "ref" field to the RPC API - it makes no sense.

Update bug

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

Differences:

• BzAPI requires a valid "token" field.
• BzAPI optionally does mid-air collision detection (by setting "last_change_time"). The RPC API does not.
• BzAPI 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 BzAPI 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 BzAPI handles that.
• The RPC API permits the setting of "remaining_time", which is Read Only in BzAPI.
• BzAPI 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 BzAPI does.

REST Unification Proposal: We can abolish the need for a token; that is an artifact of the way the current REST implementation works on the back end. I would say we should keep the differences between RPC and REST relating to add/remove/set - that's a philosophical difference arising from the two different API types. The same is true in the smaller case of the methods of resetting assignee and QA contact to default. We should change BzAPI to return change information. We should look at adding mid-air collision detection to the RPC API, as it's a useful feature.

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).

REST Unification Proposal: If we think it's worth it, we could add a /bug/<id>/comment/<id> call to return individual comments by ID, but I didn't add this to the API originally because I thought no-one would use it. And no-one has asked for it. So I suggest REST does not need that ability. Other than that, BzAPI can start returning these missing fields, except for deprecated ones.

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".

REST Unification Proposal: add work_time to REST.

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 returns User objects rather than email addresses for the 'changer' field

REST Unification Proposal: The REST field names "changer" and "change_time" were chosen to be consistent with the other "people names" like "assignee" and "creator", and other "time names" like "last_modified_time" etc. We should use those for both implementations. We are already updating "attacher" to "creator" on the RPC attachment call, which sets a precedent.

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.
• BzAPI returns "ref", "bug_ref", and "encoding" (only "base64" supported) fields which the RPC API does not.
• BzAPI returns "description"; the RPC API also returns it, but is moving to call it "summary"
• BzAPI returns "attacher"; the RPC API also returns it but is moving to call it "creator"
• BzAPI does not have "creation_date" and "modification_date" for flags.
• The RPC API returns a "last_change_time"; BzAPI does not.
• BzAPI does not return attachment data by default.

REST Unification Proposal: There are two REST APIs here mapping to a single RPC API. This REST API's URL structure is under /bug/<id> and so it makes sense for it to continue to return the attachments for that bug only. If there was demand (although I've not seen any), we could add a /attachment GET top-level attachment search call which could return attachments across multiple bugs. But the bug search interface already allows some searching by attachment data. The encoding field can be dropped if we are sure we'll never support anything other than base64, or if we have an API versioning scheme so we can add it back later if necessary. The REST field names could migrate to follow what RPC is doing, with a transition period. BzAPI needs to return the missing fields. But I think it's wisest not to return attachment data by default - the principle of least surprise suggests you should opt in to a 15MB or more blob of data.

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.
• BzAPI returns "ref", "bug_ref", and "encoding" (only "base64" supported) fields which the RPC API does not.
• BzAPI returns "description"; the RPC API also returns it, but is moving to call it "summary"
• BzAPI returns "attacher"; the RPC API also returns it but is moving to call it "creator"
• BzAPI does not have "creation_date" and "modification_date" for flags.
• The RPC API returns a "last_change_time"; BzAPI does not.
• BzAPI does not return attachment data by default.

REST Unification Proposal: See above, as there are two REST APIs here mapping to a single RPC API.

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. BzAPI does not.
• The above also means the RPC API takes an "ids" array whereas BzAPI takes a "bug_id" parameter.
• BzAPI allows you to add a comment at the same time; the RPC API does not.
• BzAPI uses "description"; RPC is moving to use "summary".
• BzAPI allows you to set flags on the attachment; the RPC API does not.

REST Unification Proposal: BzAPI could not add the ability to post to multiple bugs at once (who uses that?) because the URL structure indicates a single bug. The RPC API needs to grow BzAPI's other abilities here, but REST needs to migrate to "summary" from "description".

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.

REST Unification Proposal: expand REST API to allow searching by list of IDs 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.

REST Unification Proposal: Leave as-is.

Configuration Calls: Details

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

REST Unification Proposal: this is a tricky one. Do users want the comprehensive data dump in one go, which might be useful e.g. for producing a graphical Bugzilla client? Or do they want limited and targetted access to certain property values? The trouble with this is that you can end up having to make many, many calls to get the full picture. I would say a single call with good field control (which the current REST API does not have) is the way to go, but I can see that this is a point of debate.

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 Unification Proposal: Implement as 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 Unification Proposal: Implement as GET /time, with only the db_time and web_time parameters at most (the others are deprecated). db_time and web_time are expected to be less than a second apart - is it really necessary to return them both?

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 Unification Proposal: Implement as GET /parameters.

Get the latest time from the audit_log table

• Bugzilla.last_audit_time

Example:

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

REST Unification Proposal: Implement as GET /last_audit_time. (Why does this need to be a separate, specific call? What is the use case for it? -- Gerv)

Get info about products a user can search on

• Product.get_selectable_products

Example:

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

REST Unification Proposal: Implement as GET /product?type=selectable (default type = accessible). We should return Product objects with full info, not simply a list of IDs.

Get info about products a user can enter bugs against

• Product.get_enterable_products

Example:

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

REST Unification Proposal: Implement as GET /product?type=enterable. We should return Product objects with full info, not simply a list of IDs.

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

• Product.get_accessible_products

Example:

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

REST Unification Proposal: Implement as GET /product?type=accessible. We should return Product objects with full info, not simply a list of IDs.

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 Unification Proposal: Implement as 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 Unification Proposal: Implement as PUT /group/15. (We need to discuss return values - BzAPI currently does not return change information of the above form. -- Gerv)

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 Unification Proposal: Implement as 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 Unification Proposal: Implement as PUT /product/35. (We need to discuss return values - BzAPI currently does not return change information of the above form. -- Gerv)

Offer account by email

• User.offer_account_by_email

Example:

Request:

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

Response: None

REST Unification Proposal: Implement as 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 Unification Proposal: Implement as POST /user.

Update a user account

• User.update

Example:

Request:

 {
   'names': 'test@mozilla.com',
   'full_name: 'New Full Name'
 }

Response:

 {
   'users': [
     {
       'id': '12345',
       'changes': {
         'full_name': {
           'added': 'New Full Name',
           'removed': 'Old Full Name'
         }
       }
     }
   ]
 }

REST Unification Proposal: Implement as PUT /user/<email>. (We need to discuss return values - BzAPI currently does not return change information of the above form. -- Gerv)

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:

Philosophical Design Differences

An RPC API is "Remote Procedure Call" - the idea is that you call a function on the server which does what you want, and returns. A REST API is REpresentational State Transfer - the idea is that you transfer the full state of an object in either direction, which would be the entire new state if you are updating it. This difference means that a good RPC API and a good REST API will inevitably have different approaches on some points. So, for example, the RPC API has a Bug.update_see_also call, which only updates the See Also field. That makes perfect sense in an RPC world, but not in a REST world, where the appropriate way of updating a bug is to get a copy of it, modify it, and resend that modified copy back again.

Another example is that REST URLs refer to individual objects - e.g. /bug/<id> GET refers to a single bug. Multiple bugs are retrieved using the /bug GET search API. In BzAPI, it seems that both the search and the bug retrieval API have the ability to return multiple bugs. Again, this is fine for a remote procedure call, but is not REST-y.

Objects vs. IDs

REST uses User objects whereas RPC uses filtered email addresses depending on whether the user is logged in. RPC uses Product IDs; REST uses (or would use) Product objects. This is also an issue for Group objects vs. group names in the bug retrieval API. This is an outworking of the "full state" principle mentioned above.

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". BzAPI has only a "set" model, because of the differences exampled above.

Config information

BzAPI 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, although not one which comes directly from REST principles. The resolution of this difference one way or the other will be more pragmatic.

Error handling

BzAPI returns various different flavors of error depending on the underlying implementation, whereas the RPC API simply returns an error code and description. The REST errors need to be more standardized.

REST also makes use of HTTP status codes to designate types of errors. RPC normally returns the same HTTP 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