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.
Contents
- 1 High Level
- 2 Matching Calls: Details
- 3 Configuration Calls: Details
- 4 RPC Calls Not In REST: Details
- 4.1 Get list of installed extensions
- 4.2 Get info about Bugzilla's notions of time
- 4.3 Get safe parameter values
- 4.4 Get the latest time from the audit_log table
- 4.5 Get info about products a user can search on
- 4.6 Get info about products a user can enter bugs against
- 4.7 Get info about products a user can search or enter bugs against
- 4.8 Create a new group
- 4.9 Update info about a group
- 4.10 Create a new product
- 4.11 Update info about a product
- 4.12 Offer account by email
- 4.13 Create a user account
- 4.14 Update a user account
- 5 REST Calls Not In RPC: Details
- 6 Missing Calls in REST and RPC
- 7 Meta Issues
- 8 Scratchpad
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