New WebService functions discussion

[Noura Elhawary]

Hi All,

Few points I would like to discuss with you in the upcoming bugzilla
meeting. It is all related to the new WebService functions that have
milestone 4.0 currently set for them. I wasn't sure if it is a good idea
to put these notes in the meeting wiki as they are so detailed so maybe
here is a good place for them. Please take a look at them, I hope we can
reach a decision on them by the next meeting :)

NOTE : Bug ids are included in the issues related to them.


Bugzilla/WebService/User.pm
----------------------------
1- API consistency between the different User.pm functions , the
following names are the ones that should be used for the API's different
functions in the passed hash params and also in the returned values:
 
User fields: id, name, real_name, email, can_login, email_enabled,
             disabled_text

Note: We might need to change the param name 'full_name' in User.create 
     to 'real_name' to match the other API functions User.get Bug#412725
     and User.update Bug#416137

2- User.get(), Bug#412725 : 
   - Security Issue: only users in 'editusers' group gets the following
     information about other users: disabled_text, email_enabled, and 
     and can_login.


3- User.update(), Bug#416137:
  - User needs to be in 'editusers' group to be able to update other 
    user's information ,, this is the only privilege needed.
  - The changes hash returned from calling $user.update will be 
    returned to the user, but the names will be overridden to match
    with the agreed user field names for API consistency.
  - If User.update() will eventually be allowed to update permissions as
    well, then we will need to allow persons with bless privileges for 
    particular groups to be allowed to add/remove users from those 
    groups.
  - shall we call the hash key update, updates just to consistent with
    ids and names in the passed parameters hash.

---------------------------------------------------------------------------

Bugzilla/WebService/Bug.pm
---------------------------
1- Bug.get(), Bug#413770:
  - It is more user friendly and more useful to return names instead of 
    ids , so all returned user ids for bug reporter,assigned_to , 
    qa_contact, product and component should be converted to names, 
    or we can return both names and ids. Or reporter, assigned_to, etc 
    could be a hashes that contains the user info such as id, email, 
    real_name, etc. component would be hash containing id, name, etc.

  - Bug.get can give three different types of returns depending on the 
    passed parameters:
      - passing only bug ids  $rpc->call('Bug.get', {ids => [1,2]})
        returns only basic information in the bug object similar 
        to the current behavior but with names returned.

      - passing bug ids and all flag , 
        $rpc->call('Bug.get', {ids => [1,2], all => 1})
        returns all bug information that we can get from bug object
        and by calling the accessor functions to get: cc, dependson, 
        blocked, longdescs, keywords, groups, attachments, 
        flag_types, dup_id, actual_time and milestoneurl
      
      - specifying the fields we want in return:
       $rpc->call('Bug.get',{ids =>[1,2],fields =>[priority, keywords]})
       and this will return only the fields requested.

2- Bug.get_activity(), Bug#424079:
   - The function gets list of bug ids/aliases and returns hash
     with keys: id, alias, incomplete_data and operation , maybe 
     can use better names as data_iscomplete and history
   - should this function be separate or should we include it
     in Bug.get() .. so would be something like this:
     $rpc->call('Bug.get',{ids =>[1,2],fields =>[bugs_activity]}) 
     or
     $rpc->call('Bug.get',{ids =>[1,2], bugs_activity => 1})

3- Bug.update(), Bug#418342:
   - depends on the function set_all,, is it ready now to write it and 
     change process_bug.cgi to use it? 
     2 issues were blocking set_all : 1- ability to make mass bug 
     updates for everything except bug alias , and moving sending email
     code from process_bug.cgi ? so is it right time to start writing
     set_all now?

-------------------------------------------------------------------------

Bugzilla/WebService/Component.pm, 
--------------------------------
1- API consistency between Component.pm functions, the following names
   should be used for component fields in passed parameters or returned
   values: 
   Component fields: id, name, product_name, product_id, default_cc
                     default_assigned_to, default_qa_contact

   using default_* will cause writing some extra code for 
   Component.update to change the names returned in the changes
   hash from $component.update to match with the above names
   for API consistency ,, is there any plans that default_*
   names will be the ones used all over the code , replacing
   initailowner, initialqacontact, etc ?

2- Security Issue: Non privileged users shouldn't be able to know 
   about the existence of confidential products when they try to
   update or get components they can not access. Solution: is to 
   get $user->get_accessible_products() for the user and check that 
   the product names they passed is in their accessible list of 
   products. Please take a look at the patch in Bug#385282 for 
   that solution.

3- Component.update(), Bug#419456:
   - code is getting a bit complicated in this function for 2 reasons:
     a- change the names returned in the changes hash to match with
        the selected component field names for API consistency.
     b- convert user ids returned in the changes hash to login names.
     
4- Component.get_by_product, Bug#424921:
   - shall this function be separate or should it be in Component.get?
     I vote for making it separate because the returned value has 
     different format to Component.get, this function should return 
     component information grouped by passed product names, where as 
     Component.get will return single component information for each
     passed component?

-----------------------------------------------------------------------
 
One last general note: shall we allow the values passed into the
WebService functions to be single as well as lists for example for 
User.get we can have

$rpc->call('User.get', { ids => [1,2]}) 
or
$rpc->call('User.get, {ids => 1})

do in the function code we will expect both by :
my @ids = ref($params->{ids}) ? @{$params->{ids}} : ($params->{ids});

--------------------------------------------------------------------


Thanks,
Noura