Bugzilla:API Comparison

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

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). This will hopefully be useful data as we figure out how to align them, as Bugzilla implements a native REST API.

High Level

Matching Calls

Function	REST	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 REST /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 REST

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 REST

Function	RPC
Log in to RPC interface	User.login
Log out of RPC interface	User.logout

Deprecated

RPC
Bugzilla.timezone
Bug.legal_values

REST Calls Not In RPC

Function	REST
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:

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

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

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

/bug/<id> GET -- Bug.get

Differences:

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 time tracking fields are defined as double in RPC, and Decimal in REST.
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.

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

/bug/<id> PUT -- Bug.update / Bug.update_see_also / Bug.update_tags

Differences:

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

/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. Other than that, the REST API 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 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

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

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

/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.
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: 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. 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 uses "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.

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.

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.

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

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.

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.

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.

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.

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>

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, 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

REST uses User objects whereas RPC uses filtered email addresses depending on whether the user is logged in. 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.

This is also an issue for Group objects vs. group names in the bug retrieval API.

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.

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.

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.

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.

Scratchpad

Need to check if there are differences in include_fields/exclude_fields handling -- see bug 540818

Bugzilla:API Comparison

High Level

Matching Calls

RPC Calls Supplying Subsets of REST /config Call

RPC Calls Not In REST

User

Admin

Not Needed For REST

Deprecated

REST Calls Not In RPC

Matching Calls: Details

Search for bugs

Create new bug

Retrieve bug

Update bug

List comments for bug

Add new comment to bug

List history for bug

List attachments for bug

Retrieve attachment

Create new attachment

Search for users

Retrieve user

Configuration Calls: Details

Get current Bugzilla version

Get info about classifications by name or ID

Get info about products

Get info about fields and their legal values

RPC Calls Not In REST: Details

Get list of installed extensions

Get info about Bugzilla's notions of time

Get safe parameter values

Get the latest time from the audit_log table

Get info about products a user can search on

Get info about products a user can enter bugs against

Get info about products a user can search or enter bugs against

Create a new group

Update info about a group

Create a new product

Update info about a product

Offer account by email

Create a user account

Update a user account

REST Calls Not In RPC: Details

List flags for bug

Count bugs

Update attachment metadata

Get Configuration

Missing Calls in REST and RPC

Get information about a group

Meta Issues

Philosophical Design Differences

User vs email

Multiple values for a field

Config information

Error handling

Scratchpad

Navigation menu

Search