Account confirmers, Anti-spam team, Confirmed users, Bureaucrats and Sysops emeriti
4,925
edits
Bugzilla:API Comparison: Difference between revisions
Jump to navigation
Jump to search
no edit summary
No edit summary |
No edit summary |
||
| Line 144: | Line 144: | ||
The following differences are copied from the analysis of the call for returning a single bug. | The following differences are copied from the analysis of the call for returning a single bug. | ||
* 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 returns User objects instead of email addresses. | ||
* The REST API does not return "creation_date" or "modification_date" on flags. | * The REST API does not return "creation_date" or "modification_date" on flags. | ||
| Line 152: | Line 153: | ||
* 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. | 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=== | ===Create new bug=== | ||
| Line 166: | Line 167: | ||
* 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. | 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=== | ===Retrieve bug=== | ||
| Line 187: | Line 188: | ||
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. | 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=== | ===Update bug=== | ||
| Line 205: | Line 206: | ||
* 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 | 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. | ||
===List comments for bug=== | ===List comments for bug=== | ||
| Line 223: | Line 224: | ||
* 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. | 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. | ||
===Add new comment to bug=== | ===Add new comment to bug=== | ||
| Line 248: | Line 249: | ||
* RPC "who" field is "changer" in BzAPI | * RPC "who" field is "changer" in BzAPI | ||
* RPC "when" field is "change_time" in BzAPI | * RPC "when" field is "change_time" in BzAPI | ||
* 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: | 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=== | ===List attachments for bug=== | ||
| Line 267: | Line 267: | ||
* 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. | 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. | ||
===Retrieve attachment=== | ===Retrieve attachment=== | ||
| Line 294: | Line 294: | ||
* The above also means the RPC API takes an "ids" array whereas the REST API takes a "bug_id" parameter. | * 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 allows you to add a comment at the same time; the RPC API does not. | ||
* The REST API uses "description"; RPC | * 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. | * 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. | 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". | ||
===Search for users=== | ===Search for users=== | ||
| Line 392: | Line 392: | ||
} | } | ||
REST Unification Proposal: Implement as GET /time. | 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=== | ===Get safe parameter values=== | ||
| Line 424: | Line 424: | ||
} | } | ||
REST Unification Proposal: Implement as GET /last_audit_time. | 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=== | ===Get info about products a user can search on=== | ||
| Line 442: | Line 442: | ||
} | } | ||
REST Unification Proposal: Implement as GET /product?type=selectable (default type = accessible). | 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=== | ===Get info about products a user can enter bugs against=== | ||
| Line 460: | Line 460: | ||
} | } | ||
REST Unification Proposal: Implement as GET /product?type=enterable. | 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=== | ===Get info about products a user can search or enter bugs against=== | ||
| Line 478: | Line 478: | ||
} | } | ||
REST Unification Proposal: Implement as GET /product?type=accessible. | 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=== | ===Create a new group=== | ||
| Line 532: | Line 532: | ||
} | } | ||
REST Unification Proposal: Implement as PUT /group/15. | 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) | ||
===Create a new product=== | ===Create a new product=== | ||
| Line 590: | Line 590: | ||
} | } | ||
REST Unification Proposal: Implement as PUT /product/35. | 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) | ||
===Offer account by email=== | ===Offer account by email=== | ||
| Line 659: | Line 659: | ||
} | } | ||
REST Unification Proposal: Implement as PUT /user/<email> | 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) | ||
==REST Calls Not In RPC: Details== | ==REST Calls Not In RPC: Details== | ||
| Line 695: | Line 695: | ||
===Philosophical Design Differences=== | ===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. | 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 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. | 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. | ||
=== | ====Objects vs. IDs==== | ||
REST uses User objects whereas RPC uses filtered email addresses depending on whether the user is logged in. | 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". The REST API has only a "set" model, because of the differences exampled above. | |||
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 | |||
===Config information=== | ===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. | 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. | ||
===Error handling=== | ===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. | 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. | ||
REST also makes use of | 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== | ==Scratchpad== | ||
* Need to check if there are differences in include_fields/exclude_fields handling -- see {{bug|540818}} | * Need to check if there are differences in include_fields/exclude_fields handling -- see {{bug|540818}} | ||