Bugzilla:API Comparison: Difference between revisions

This page attempts to list the differences between the Bugzilla [http://www.bugzilla.org/docs/tip/en/html/api/ XML-RPC/JSON-RPC API] (on the Bugzilla tip) and the [[Bugzilla:BzAPI|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 [https://bugzilla.mozilla.org/show_bug.cgi?id=866927 native REST API]. ** This is now complete - see [[Bugzilla:REST_API]] **.

! REST

===RPC Calls Supplying Subsets of REST /config Call===

===RPC Calls Not In REST===

====Not Needed For REST====

===REST Calls Not In RPC===

! REST

* 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 REST API by default only returns those fields which can be returned by a Bugzilla search; the RPC returns a lot more fields by default. The REST API can return the others, but it does an extra request under the covers.  

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

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

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

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

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 the REST API to return change information. We should look at adding mid-air collision detection to the RPC API, as it's a useful feature.

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, the REST API can start returning these missing fields, except for deprecated ones.

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

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. The REST API 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.

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

* 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 is moving to use "summary".

* The REST API allows you to set flags on the attachment; the RPC API does not.

REST Unification Proposal: The REST API 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 the REST API's other abilities here, but REST needs to migrate to "summary" from "description".

REST Unification Proposal: Implement as PUT /group/15. (We need to discuss return values - the REST API currently does not return change information of the above form. -- Gerv)

REST Unification Proposal: Implement as PUT /product/35. (We need to discuss return values - the REST API currently does not return change information of the above form. -- Gerv)

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

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 the REST API, 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.

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, because of the differences exampled above.

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

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. The REST errors need to be more standardized.