Account confirmers, Anti-spam team, Confirmed users, Bureaucrats and Sysops emeriti
4,925
edits
Bugzilla:API Comparison: Difference between revisions
no edit summary
(Use tables) |
No edit summary |
||
| Line 1: | Line 1: | ||
{{draft}} | |||
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:REST_API|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 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:REST_API|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]. | ||
| Line 149: | Line 151: | ||
* The REST API does not return the "is_open" field. | * The REST API does not return the "is_open" field. | ||
* The REST API returns a "ref" field. | * The REST API 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. | |||
===Create new bug=== | ===Create new bug=== | ||
| Line 161: | Line 165: | ||
* The BzAPI call takes User objects rather than flat email addresses. | * 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 [http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Bug.html#create limited set of fields]. | * 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 [http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Bug.html#create 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. 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. | |||
===Retrieve bug=== | ===Retrieve bug=== | ||
| Line 180: | Line 186: | ||
Other than that, field name compatibility is very good. | 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. (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=== | ===Update bug=== | ||
| Line 196: | Line 204: | ||
* 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 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. | * The RPC API returns much more info about the bug and the change than the REST API does. | ||
REST Unification Proposal: 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 for the methods of resetting assignee and QA contact to default. We should change the REST API to return change information. Re: mid-air collision detection - can that be added to the RPC API? It's a useful feature. | |||
===List comments for bug=== | ===List comments for bug=== | ||
| Line 212: | Line 222: | ||
* 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 "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). | * 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. Other than that, the REST API can start returning these missing fields, except for deprecated ones. | |||
===Add new comment to bug=== | ===Add new comment to bug=== | ||
| Line 223: | Line 235: | ||
* BzAPI does not support the "work_time" parameter. | * BzAPI does not support the "work_time" parameter. | ||
* BzAPI return value includes a "ref" as well as an "id". | * BzAPI return value includes a "ref" as well as an "id". | ||
REST Unification Proposal: add work_time to REST. | |||
===List history for bug=== | ===List history for bug=== | ||
| Line 236: | Line 250: | ||
* 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 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 | * The BzAPI call returns User objects rather than email addresses for the 'changer' field | ||
REST Unification Proposal: The RPC API tries to use modern field names elsewhere; perhaps it doesn't on the History call because they are read from the DB? Anyway, if we can version the API, it should change to use modern field names. The REST field names "changer" and "change_time" were chosen to be consistent with the other "people names" like "assignee", and other "time names" like "last_modified_time" etc. We should retain those. | |||
===List attachments for bug=== | ===List attachments for bug=== | ||
| Line 250: | Line 266: | ||
* The RPC API returns a "last_change_time"; the REST API does not. | * The RPC API returns a "last_change_time"; the REST API does not. | ||
* The REST API does not return attachment data by default. | * 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. The other option would be to add a /attachment GET top-level attachment search call which could return attachments across multiple bugs. 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 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. | |||
===Retrieve attachment=== | ===Retrieve attachment=== | ||
| Line 264: | Line 282: | ||
* The RPC API returns a "last_change_time"; the REST API does not. | * The RPC API returns a "last_change_time"; the REST API does not. | ||
* The REST API does not return attachment data by default. | * The REST API 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=== | ===Create new attachment=== | ||
| Line 276: | Line 296: | ||
* The REST API uses "description"; RPC uses "summary". | * The REST API uses "description"; RPC uses "summary". | ||
* The REST API allows you to set flags on the attachment; the RPC API does not. | * 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. | |||
===Search for users=== | ===Search for users=== | ||
| Line 286: | Line 308: | ||
* REST only supports search by name matching. RPC supports an exact name list, name matching, an ID list, and/or group. | * 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=== | ===Retrieve user=== | ||
| Line 296: | Line 320: | ||
* REST supports retrieving individual users by ID or by name. RPC just has the general search call which can be made specific. | * 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== | ==Configuration Calls: Details== | ||
BzAPI has a single call to get a large config data structure, whereas the RPC API is more fine-grained. | 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=== | ===Get current Bugzilla version=== | ||
| Line 322: | Line 350: | ||
* Bugzilla.extensions | * Bugzilla.extensions | ||
Example: | Example: | ||
| Line 348: | Line 375: | ||
REST Proposal: | REST Unification Proposal: Implement as GET /extensions. | ||
GET /extensions | |||
===Get info about Bugzilla's notions of time=== | ===Get info about Bugzilla's notions of time=== | ||
* Bugzilla.time | * Bugzilla.time | ||
Example: | Example: | ||
| Line 368: | Line 392: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as GET /time. | ||
GET /time | |||
===Get safe parameter values=== | ===Get safe parameter values=== | ||
| Line 390: | Line 412: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as GET /parameters. | ||
GET /parameters | |||
===Get the latest time from the audit_log table=== | ===Get the latest time from the audit_log table=== | ||
| Line 404: | Line 424: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as GET /last_audit_time. | ||
GET /last_audit_time | |||
===Get info about products a user can search on=== | ===Get info about products a user can search on=== | ||
| Line 424: | Line 442: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as GET /product?type=selectable (default type = accessible). | ||
GET /product?type=selectable (default type = accessible) | |||
===Get info about products a user can enter bugs against=== | ===Get info about products a user can enter bugs against=== | ||
| Line 444: | Line 460: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as GET /product?type=enterable. | ||
GET /product?type=enterable | |||
===Get info about products a user can search or enter bugs against=== | ===Get info about products a user can search or enter bugs against=== | ||
| Line 464: | Line 478: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as GET /product?type=accessible. | ||
GET /product?type=accessible | |||
===Create a new group=== | ===Create a new group=== | ||
| Line 489: | Line 501: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as POST /group. | ||
POST /group | |||
===Update info about a group=== | ===Update info about a group=== | ||
| Line 522: | Line 532: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as PUT /group/15. | ||
PUT /group/15 | |||
===Create a new product=== | ===Create a new product=== | ||
| Line 551: | Line 559: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as POST /product. | ||
POST /product | |||
===Update info about a product=== | ===Update info about a product=== | ||
| Line 584: | Line 590: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as PUT /product/35. | ||
PUT /product/35 | |||
===Offer account by email=== | ===Offer account by email=== | ||
| Line 602: | Line 606: | ||
Response: None | Response: None | ||
REST Proposal: | REST Unification Proposal: Implement as POST /user/<email>. | ||
POST /user/email | |||
===Create a user account=== | ===Create a user account=== | ||
| Line 626: | Line 628: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as POST /user. | ||
POST /user | |||
===Update a user account=== | ===Update a user account=== | ||
| Line 659: | Line 659: | ||
} | } | ||
REST Proposal: | REST Unification Proposal: Implement as PUT /user/<email> | ||
PUT /user/ | |||
==REST Calls Not In RPC: Details== | ==REST Calls Not In RPC: Details== | ||
| Line 694: | Line 692: | ||
Reviewing the "Matching Calls" section, it seems that the following issues come up more than once: | 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, 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 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 not REST-y. | |||
===User vs email=== | ===User vs email=== | ||