MozillaWiki

Bugzilla:API Comparison: Difference between revisions

Bugzilla Discussion

Bugzilla:API Comparison (view source)

Revision as of 00:48, 8 July 2014

11,068 bytes added ,  8 July 2014
Changed most instances of "REST API" to "BzAPI"; updated intro
(Changed most instances of "REST API" to "BzAPI"; updated intro)
 
(33 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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:BzAPI|BzAPI REST API]] (on the BzAPI tip). The new [[Bugzilla:REST_API|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 [[Bugzilla:BzAPI:CompatLayer|BzAPI compatibility layer]].


==High Level==
==High Level==
Line 5: Line 7:
===Matching Calls===
===Matching Calls===


* Search for bugs: /bug GET -- Bug.search  
{| border="1"
* Create new bug: /bug POST -- Bug.create
! Function
* Retrieve bug: /bug/<id> GET -- Bug.get
! BzAPI
* Update bug: /bug/<id> PUT -- Bug.update / Bug.update_see_also / Bug.update_tags
! RPC
 
|-
* List comments for bug: /bug/<id>/comment GET -- Bug.comments
| Search for bugs||/bug GET||Bug.search  
* Add new comment to bug: /bug/<id>/comment POST -- Bug.add_comment
|-
* List history for bug: /bug/<id>/history GET -- Bug.history
| Create new bug||/bug POST||Bug.create
 
|-
* List attachments for bug: /bug/<id>/attachment GET -- Bug.attachments
| Retrieve bug||/bug/<id> GET||Bug.get
* Retrieve attachment: /attachment/<id> GET -- Bug.attachments
|-
* Create new attachment: /bug/<id>/attachment POST -- Bug.add_attachment
| Update bug||/bug/<id> PUT||Bug.update / Bug.update_see_also / Bug.update_tags
 
|-
* Search for users: /user GET -- User.get
| List comments for bug||/bug/<id>/comment GET||Bug.comments
* Retrieve user: /user/<id> GET -- User.get
|-
| 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 REST /config Call===
===RPC Calls Supplying Subsets of BzAPI /config Call===


* Get current Bugzilla version: Bugzilla.version
{| border="1"
* Get info about classifications by name or ID: Classification.get
! Function
* Get info about products: Product.get
! RPC
* Get info about fields and their legal values: Bug.fields
|-
| 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===
===RPC Calls Not In BzAPI===


====User====
====User====


* Get list of installed extensions: Bugzilla.extensions
{| border="1"
* Get info about Bugzilla's notions of time: Bugzilla.time
! Function
* Get safe parameter values: Bugzilla.parameters
! RPC
* 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 list of installed extensions||Bugzilla.extensions
* 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
| 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====
====Admin====


* Create a new group: Group.create
{| border="1"
* Update info about a group: Group.update
! Function
* Create a new product: Product.create
! RPC
* Update info about a product: Product.update
|-
* Offer account by email: User.offer_account_by_email
| Create a new group||Group.create
* Create a user account: User.create
|-
* Update a user account: User.update
| 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 REST====
====Not Needed For BzAPI====


* Log in to RPC interface: User.login
{| border="1"
* Log out of RPC interface: User.logout
! Function
! RPC
|-
| Log in to RPC interface||User.login
|-
| Log out of RPC interface||User.logout
|}


====Deprecated====
====Deprecated====


* Bugzilla.timezone
{| border="1"
* Bug.legal_values
! RPC
|-
| Bugzilla.timezone
|-
| Bug.legal_values
|}


===REST Calls Not In RPC===
===BzAPI Calls Not In RPC===
 
* 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)


{| border="1"
! 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==
==Matching Calls: Details==
Line 76: Line 140:
Differences:
Differences:


* 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.
* 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.
The following differences are copied from the analysis of the call for returning a single bug.


* The REST API returns User objects instead of email addresses.
* 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.
* The REST API does not return "creation_date" or "modification_date" on flags.
* BzAPI returns User objects instead of email addresses.
* The REST API returns Group objects (with name and ID) instead of group names.
* BzAPI does not return "creation_date" or "modification_date" on flags.
* The REST API includes attachment metadata by default. The RPC API does not include any attachment data at all.
* BzAPI returns Group objects (with name and ID) instead of group names.
* The REST API includes comments if you ask for them using field control. The RPC API does not include comments.
* BzAPI includes attachment metadata by default. The RPC API does not include any attachment data at all.
* The REST API does not return the "is_open" field.
* BzAPI includes comments if you ask for them using field control. The RPC API does not include comments.
* The REST API returns a "ref" field.
* 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===
===Create new bug===
Line 99: Line 166:
* 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. 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 106: Line 175:
Differences:
Differences:


* The REST API returns only a single bug; the RPC API can return multiple bugs.
* BzAPI returns only a single bug; the RPC API can return multiple bugs.
* The REST API does not support the experimental "permissive" boolean on requests.
* BzAPI does not support the experimental "permissive" boolean on requests.
* The time tracking fields are defined as double in RPC, and Decimal in REST.
* The time tracking fields are defined as double in RPC, and Decimal in REST.
* The REST API returns User objects instead of email addresses.
* BzAPI returns User objects instead of email addresses.
* The REST API does not return "creation_date" or "modification_date" on flags.
* BzAPI does not return "creation_date" or "modification_date" on flags.
* The REST API returns Group objects (with name and ID) instead of group names.
* BzAPI 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.
* BzAPI 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.
* BzAPI 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.
* BzAPI does not return the "is_open" field.
* The REST API returns a "ref" field.
* BzAPI returns a "ref" field.


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 - 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 125: Line 196:
Differences:
Differences:


* The REST API requires a valid "token" field.
* BzAPI requires a valid "token" field.
* The REST API optionally does mid-air collision detection (by setting "last_change_time"). The RPC API does not.
* BzAPI 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.
* 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 the REST API simply has a "set" model. These are "blocks", "depends_on", "cc", "groups", "keywords" and "see_also".
* 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).
* 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 the REST API handles that.
* 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 the REST API.
* The RPC API permits the setting of "remaining_time", which is Read Only in BzAPI.
* 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".
* 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 the REST API does.
* 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===
===List comments for bug===
Line 150: Line 223:
* 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. 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===
===Add new comment to bug===
Line 161: Line 236:
* 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 172: 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 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 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 182: Line 260:


* 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.
* 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.
* The REST API returns "ref", "bug_ref", and "encoding" (only "base64" supported) fields which the RPC API does not.
* BzAPI 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"
* BzAPI 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"
* BzAPI 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.
* BzAPI does not have "creation_date" and "modification_date" for flags.
* The RPC API returns a "last_change_time"; the REST API does not.
* The RPC API returns a "last_change_time"; BzAPI does not.
* The REST API does not return attachment data by default.
* 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===
===Retrieve attachment===
Line 196: Line 276:


* 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.
* 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.
* The REST API returns "ref", "bug_ref", and "encoding" (only "base64" supported) fields which the RPC API does not.
* BzAPI 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"
* BzAPI 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"
* BzAPI 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.
* BzAPI does not have "creation_date" and "modification_date" for flags.
* The RPC API returns a "last_change_time"; the REST API does not.
* The RPC API returns a "last_change_time"; BzAPI does not.
* The REST API does not return attachment data by default.
* 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===
===Create new attachment===
Line 209: Line 291:
Differences:
Differences:


* The RPC API allows a single uploaded attachment to be added to multiple bugs at once. The REST API does not.
* 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 the REST API takes a "bug_id" parameter.
* The above also means the RPC API takes an "ids" array whereas BzAPI takes a "bug_id" parameter.
* The REST API allows you to add a comment at the same time; the RPC API does not.
* BzAPI allows you to add a comment at the same time; the RPC API does not.
* The REST API uses "description"; RPC uses "summary".
* BzAPI uses "description"; RPC is moving to use "summary".
* The REST API allows you to set flags on the attachment; the RPC API does not.
* 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===
===Search for users===
Line 224: 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 234: 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 260: Line 350:


* Bugzilla.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===
===Get info about Bugzilla's notions of time===


* Bugzilla.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===
===Get safe parameter values===


* Bugzilla.parameters
* 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===
===Get the latest time from the audit_log table===


* Bugzilla.last_audit_time
* 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===
===Get info about products a user can search on===


* Product.get_selectable_products
* 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===
===Get info about products a user can enter bugs against===


* Product.get_enterable_products
* 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===
===Get info about products a user can search or enter bugs against===


* Product.get_accessible_products
* 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===
===Create a new group===


* Group.create
* 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===
===Update info about a group===


* Group.update
* 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===
===Create a new product===


* Product.create
* 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===
===Update info about a product===


* Product.update
* 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===
===Offer account by email===


* User.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===
===Create a user account===


* User.create
* 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===
===Update a user account===


* User.update
* 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==
==REST Calls Not In RPC: Details==
Line 334: Line 682:


(although some config stuff is available as more specific calls)
(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==
==Meta Issues==
Line 339: Line 693:
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:


===User vs email===
===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.


REST uses User objects whereas RPC uses flat email addresses. The question here is whether the display name (and perhaps other info) about the user is sufficiently useful on a regular basis to be made part of the returned data. If it is, that would suggest moving to what REST does. If not, that would suggest moving towards what RPC does.
====Objects vs. IDs====


This is also an issue for Group objects vs. group names in the bug retrieval API.
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===
====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. This is an API design difference.
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===
===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.
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===
===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.
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 as well. RPC normally returns the same status code even in an error condition and the client checks the payload to see if an error occurred.
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}}
Mcote
Confirmed users
1,927

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/659841...995225"