Changes between Version 11 and Version 12 of NewTestbedAPISpec


Ignore:
Timestamp:
Aug 12, 2013 12:39:12 PM (11 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • NewTestbedAPISpec

    v11 v12  
    156156 * a modification type: elements may be read/write, read-only (e.g., username) or write-only (e.g., password)
    157157 * a brief description of the field, intended to be presented by a web interface or other third party program
     158 * an ordering hint for web interfaces presenting the data to users, an integer
     159 * an optional length hint to give a web interface a hint as to how big an input field to present.  0 indicates no hint.
    158160
    159161To get a profile schema, for example to create an empty web page,
    … …  
    171173       * double
    172174       * binary/opaque
    173      * StringValue - a string containing the element's value, unless it is binary/opaque
    174      * BinaryValue - a byte string containing the element's value if it is binary/opaque
     175     * Value - a string containing the element's value
    175176     * Access - a 32-bit integer describing the access values (values at [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/user/UserAttribute.html Attribute's javadoc])
    176177       * READ_WRITE
    … …  
    182183     * Format - a regular expression that can be used to validate the field entry (may be null, and generally is for optional fields)
    183184     * FormatDescription - A brief, natural language description of the field input constraints, e.g. "A valid e-mail address" or "only numbers and spaces".
     185     * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
     186     * LengthHint - an integer suggesting how long an input firld should be presented
    184187
    185188To read a user's profile (generally only users can read their own profile).
    … …  
    198201       * double
    199202       * binary/opaque
    200      * StringValue - a string containing the element's value, unless it is binary/opaque
    201      * BinaryValue - a byte string containing the element's value if it is binary/opaque
     203     * Value - a string containing the element's value
    202204     * Access - a 32-bit integer describing the access values (values at [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/user/UserAttribute.html Attribute's javadoc])
    203205       * READ_WRITE
    … …  
    207209     * Removable - a flag true if the field can be removed
    208210     * Description - a string explaining the field
     211     * Format - a regular expression that can be used to validate the field entry (may be null, and generally is for optional fields)
     212     * FormatDescription - A brief, natural language description of the field input constraints, e.g. "A valid e-mail address" or "only numbers and spaces".
     213     * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
     214     * LengthHint - an integer suggesting how long an input field should be presented
    209215
    210216Finally a user can modify a profile:
    … …  
    216222   * A list of change requests. Each request contains
    217223     * Name - the name of the field to change
    218      * StringValue - the new value of the field if this is not an opaque/binary field
    219      * BinaryValue - the new value of the field if this is an opaque/binary field
     224     * Value - the new value of the field
    220225     * Delete - a flag, if true delete the field rather than modify it
    221226 * '''Return Values:'''
    … …  
    272277
    273278 * '''Service:''' Users
    274  * '''Operation:''' sendNotifications
     279 * '''Operation:''' sendNotification
    275280 * '''Input Parameters:'''
    276281   * Users - a list of uids to receive the notification
    … …  
    291296   * A list of profile elements each containing
    292297     * Name - a string, the element's name
     298     * StringValue - a string containing the element's value
     299 * '''Return Values:'''
     300  * The userid actually created
     301
     302Note that all non-optional fields must be provided, so this is best preceeded by a call to getProfileDescription to learn the fields.
     303
     304A base userid is constructed, either from the userid presented or from a required field in the profile.  If that base userid is available, that a user with that userid is created.  Otherwise the userid is disambiguated until there are no collisions.  The userid actually created is returned.
     305
     306The user is created without membership in any projects and without a password.  A password reset challenge (equivalent to one issued by requestPasswordReset) is issued and the challenge e-mailed to the user at the address in the profile.
     307
     308Administrators can create users without the confirmation step:
     309
     310 * '''Service:''' Users
     311 * '''Operation:''' createUserNoConfirm
     312 * '''Input Parameters:'''
     313   * Userid - the requested userid (optional)
     314   * A list of profile elements each containing
     315     * Name - a string, the element's name
    293316     * StringValue - a string containing the element's value, unless it is binary/opaque
     317   * clearpassword - an optional string given the cleartext password
     318   * hash - an optional string containing a hashed password
     319   * hashtype - an optional string giving the type of hash
    294320 * '''Return Values:'''
    295321  * The userid actually created
    296322
    297 Note that all non-optional fields must be provided, so this is best preceeded by a call to getProfileDescription to learn the fields.
    298 
    299 A base userid is constructed, either from the userid presented or from a required field in the profile.  If that base userid is available, that a user with that userid is created.  Otherwise the userid is disambiguated until there are no collisions.  The userid actually created is returned.
    300 
    301 The user is created without membership in any projects and without a password.  A password reset challenge (equivalent to one issued by requestPasswordReset) is issued and the challenge e-mailed to the user at the address in the profile.
     323Note that either the cleartext password or the hash and type must be passed.  This interface is under for initializing the testbed or creating users in batch for something like a class.
     324
    302325
    303326Removing a user is accomplished using
    … …  
    327350   * Format - a regular expression describing the format (optional)
    328351   * Formatdescription - a natural language explanation of the format (optional)
     352   * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
     353   * LengthHint - an integer suggesting how long an input
    329354   * Def - default value of the attribute (will be set for all users)
    330355 * '''Return Values:'''
    … …  
    359384   * A list of project descriptors containing
    360385     * Name - a string contaiing the project name
     386     * Owner - the uid of the project owner
    361387     * Members - an array of structures containing
    362388       * Userid - a member's userid
    … …  
    365391         * REMOVE_USER - right to remove a user from this group
    366392         * REALIZE_EXPERIMENT - the right to realize an experiment under this group
    367      * Vetting - a flag indicating this is a vetting project
     393     * Approved - a flag indicating this project has been approved
    368394
    369395Filters are cumulative: specifying a regular expression and an owner will match on both.
    370396
     397=== Changing Project Membership ===
     398
     399Each of these changes propagates to the linked circle that controls resource permissions for the project. In particular, the permissions fields should include the union of the project and circle rights to set
     400
     401With appropriate rights a user can add another user to a project they are in.
     402The user being added must confirm this addition (below).  As a result of this call, users being added will be sent a notification including a challenge id to respond to, similar to a password change URL.  The prefix for that URL can be passed in here.
     403
     404 * '''Service:''' Projects
     405 * '''Operation:''' addUser
     406 * '''Input Parameters:'''
     407   * ProjectID - the project
     408   * Uids - the userids to add
     409   * Perms - the permissions to grant the user in this project.  The values are given here.
     410   * urlPrefix - a prefix to direct the user to a specific web interface to respond to the challenge.
     411 * '''Return Values:'''
     412   * A list of results of the form
     413     * Name - the uid being added
     414     * Success - a flag indicating success or failure
     415     * Reason - the reason for a failure
     416
     417For each user successfully added, a notification is sent.  To respond to that notification the UI must call:
     418
     419* '''Service:''' Projects
     420 * '''Operation:''' addUserConfirm
     421 * '''Input Parameters:'''
     422   * ChallengeID - the challenge being responded to
     423 * '''Return Values:'''
     424   * true if the user was subsequently added.  A fault is thrown on errors.
     425
     426Users can also request to join a project.  This requires some member of the project with ADD_USER rights to agree, so a notification is sent to all such users.
     427
     428 * '''Service:''' Projects
     429 * '''Operation:''' JoinProject
     430 * '''Input Parameters:'''
     431   * Uid - the uid to add
     432   * ProjectID - the project to join
     433   * urlPrefix - a prefix to direct the user to a specific web interface to respond to the challenge.
     434 * '''Return Values:'''
     435   * None
     436
     437The join succeeds when a user with appropriate permissions calls joinProjectConfirm.
     438Note that the user calling joinProjectConfirm sets the new user's project permissions.
     439
     440* '''Service:''' Projects
     441 * '''Operation:''' addUserConfirm
     442 * '''Input Parameters:'''
     443   * ChallengeID - the challenge being responded to
     444   * Perms - the permissions to grant the user in this project.  The values are given here.
     445 * '''Return Values:'''
     446   * true if the user was subsequently added.  A fault is thrown on errors.
     447
     448
     449Users can be removed from projects:
     450
     451 * '''Service:''' Projects
     452 * '''Operation:''' removeUsers
     453 * '''Input Parameters:'''
     454   * ProjectName - the project to change
     455   * Uids - uids to remove
     456 * '''Return Values:'''
     457   * A list of results of the form
     458     * Name - the uid being added
     459     * Success - a flag indicating success or failure
     460     * Reason - the reason for a failure
     461
     462If a user has the right to both add and remove a user, that user can change a user's permissions:
     463
     464 * '''Service:''' Projects
     465 * '''Operation:''' changePermissions
     466 * '''Input Parameters:'''
     467   * ProjectName - the project to change
     468   * Uids - the uids to manipulate
     469   * Rights - a 32-bit integer encoding the user's rights (each a flag)
     470 * '''Return Values:'''
     471   * A list of results of the form
     472     * Name - the uid being added
     473     * Success - a flag indicating success or failure
     474     * Reason - the reason for a failure
     475
    371476=== Manipulating Projects ===
    372 
    373 With appropriate rights a user can add another user to a project they are in:
    374 
    375  * '''Service:''' Projects
    376  * '''Operation:''' addUser
    377  * '''Input Parameters:'''
    378    * Userid - the requester's userid
    379    * ProjectName - the project to change
    380    * NewUser - the uid to add to the group
    381  * '''Return Values:'''
    382    * None
    383 
    384 If this fails, a fault is sent.  A call to {{{viewProjects}}} will confirm the change.
    385 
    386 Similarly, a user can be removed:
    387 
    388  * '''Service:''' Projects
    389  * '''Operation:''' removeUser
    390  * '''Input Parameters:'''
    391    * Userid - the requester's userid
    392    * ProjectName - the project to change
    393    * RemoveUser - the uid to remove from the group
    394  * '''Return Values:'''
    395    * None
    396 
    397 If a user has the right to both add and remove a user, that user can change a user's permissions:
    398 
    399  * '''Service:''' Projects
    400  * '''Operation:''' changePermissions
    401  * '''Input Parameters:'''
    402    * Userid - the requester's userid
    403    * ProjectName - the project to change
    404    * TargetUser - the uid to manipulate
    405    * Rights - a 32-bit integer encoding the user's rights (each a flag)
    406      * ADD_USER - right to add a user to this group
    407      * REMOVE_USER - right to remove a user from this group
    408      * REALIZE_EXPERIMENT - the right to realize an experiment under this group
    409  * '''Return Values:'''
    410    * None
    411477
    412478The owner of a group (and only the owner of that group) can give that privilege away:
    … …  
    421487   * None
    422488
    423 A user may request to join an existing project.  Note that the user need not be able to view or manipulate the project to make a request. The request will send a notification to users in the target group that can add users.
    424 
    425  * '''Service:''' Projects
    426  * '''Operation:''' requestJoin
    427  * '''Input Parameters:'''
    428    * Userid - the requester's userid
    429    * ProjectName - the project to join
    430  * '''Return Values:'''
    431    * None
    432 
    433 === Creating and Deleting Projects ===
    434 
    435 Non-vetting projects can be created and deleted with little overhead:
    436 
    437  * '''Service:''' Projects
    438  * '''Operation:''' createProject
    439  * '''Input Parameters:'''
    440    * Userid - the requester's userid
    441    * Name - the new project's name
    442  * '''Return Values:'''
    443    * None
    444 
    445 On success the new project is created with the calling user as owner and sole member.  The user has all rights.
    446 
    447  * '''Service:''' Projects
    448  * '''Operation:''' removeProject
    449  * '''Input Parameters:'''
    450    * Userid - the requester's userid
    451    * Name - the new project's name
    452  * '''Return Values:'''
    453    * None
    454 
    455 Generally an owner can remove a project, but removing a vetting project requires a testbed administrator.
    456 
    457 Because creating a vetting project may require review, it is more involved.  First the user retrieves the testbed's schema for information to supply:
    458 
    459  * '''Service:''' Projects
    460  * '''Operation:''' getVettingRequirements
    461  * '''Input Parameters:'''
    462  * '''Return Values:'''
    463    * A list of requirements elements each containing
     489=== Project Profiles ===
     490
     491The calls for manipulating a project profile are very similar to user profiles:
     492
     493To get a profile schema, for example to create an empty web page,
     494
     495 * '''Service:''' Projects
     496 * '''Operation:''' getProfileDescription
     497 * '''Input Parameters:'''
     498 * '''Return Values:'''
     499   * Projectid - always empty
     500   * A list of profile elements each containing
    464501     * Name - a string, the element's name
    465502     * DataType - a string giving the element's
    … …  
    468505       * double
    469506       * binary/opaque
    470      * StringValue - a string containing the element's value, unless it is binary/opaque
    471      * BinaryValue - a byte string containing the element's value if it is binary/opaque
     507     * Value - a string containing the element's value
     508     * Access - a 32-bit integer describing the access values (values at [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/user/UserAttribute.html Attribute's javadoc])
     509       * READ_WRITE
     510       * READ_ONLY
     511       * WRITE_ONLY (e.g., password)
    472512     * Optional - a flag true if the field is optional (must be present but may be empty)
     513     * Removable - a flag true if the field can be removed
    473514     * Description - a string explaining the field
    474 
    475 A web interface will gather this interface and call:
    476 
    477  * '''Service:''' Projects
    478  * '''Operation:''' createVettingProject
     515     * Format - a regular expression that can be used to validate the field entry (may be null, and generally is for optional fields)
     516     * FormatDescription - A brief, natural language description of the field input constraints, e.g. "A valid e-mail address" or "only numbers and spaces".
     517     * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
     518     * LengthHint - an integer suggesting how long an input firld should be presented
     519
     520To read a project's profile.
     521
     522 * '''Service:''' Projects
     523 * '''Operation:''' getProjectProfile
     524 * '''Input Parameters:'''
     525  * userid - a string naming the user to be retrieved
     526 * '''Return Values:'''
     527   * Projectid - the user whose profile is returned
     528   * A list of profile elements each containing
     529     * Name - a string, the element's name
     530     * DataType - a string giving the element's
     531       * string
     532       * integer
     533       * double
     534       * binary/opaque
     535     * Value - a string containing the element's value
     536     * Access - a 32-bit integer describing the access values (values at [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/user/UserAttribute.html Attribute's javadoc])
     537       * READ_WRITE
     538       * READ_ONLY
     539       * WRITE_ONLY (e.g., password)
     540     * Optional - a flag true if the field is optional (must be present but may be empty)
     541     * Removable - a flag true if the field can be removed
     542     * Description - a string explaining the field
     543     * Format - a regular expression that can be used to validate the field entry (may be null, and generally is for optional fields)
     544     * FormatDescription - A brief, natural language description of the field input constraints, e.g. "A valid e-mail address" or "only numbers and spaces".
     545     * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
     546     * LengthHint - an integer suggesting how long an input field should be presented
     547
     548Finally a user can modify a project profile:
     549 
     550 * '''Service:''' Projects
     551 * '''Operation:''' changeProjectProfile
     552 * '''Input Parameters:'''
     553   * ProjectId - the project's profile to modify
     554   * A list of change requests. Each request contains
     555     * Name - the name of the field to change
     556     * Value - the new value of the field
     557     * Delete - a flag, if true delete the field rather than modify it
     558 * '''Return Values:'''
     559   * A list of responses each containing
     560    * Name - astring with the name of the field
     561    * Success - a flag indicating if the request succeeded
     562    * Reason - a string indicating the reason if Success is false
     563
     564=== Creating and Deleting Projects ===
     565
     566Creating and removing projects are also similar to creating and removing users:
     567
     568 * '''Service:''' Projects
     569 * '''Operation:''' createProject
     570 * '''Input Parameters:'''
     571   * ProjectId - the new project's name
     572   * Uid - the new owner's uid (usually the caller)
     573   * profile - a list of attributes that will make up the project's profile
     574   * A list of profile elements each containing
     575     * Name - a string, the element's name
     576     * StringValue - a string containing the element's value
     577 * '''Return Values:'''
     578   * None
     579
     580As with users, all required (non-optional) fields in the profile must be provided.  The project will be created, but have no rights until approved.
     581
     582Approval is a result of the testbed's vetting process.  The user will be sent a notification when their project is approved.  When approved this call is made by an admin.
     583
     584 * '''Service:''' Projects
     585 * '''Operation:''' approveProject
     586 * '''Input Parameters:'''
     587   * ProjectID - the project's name
     588   * approved - a boolean, the new approval state
     589 * '''Return Values:'''
     590   * None
     591
     592Note that this call can be used to un-approve a previously approved project.
     593
     594On success the new project is created with the calling user as owner and sole member.  The user has all rights.
     595
     596 * '''Service:''' Projects
     597 * '''Operation:''' removeProject
    479598 * '''Input Parameters:'''
    480599   * Userid - the requester's userid
    481    * Name - a string containing the project name
    482    * A (possibly empty) list of vetting info fields requests. Each request contains
    483      * Name - the name of the field supplied
    484      * StringValue - the value of the field if this is not an opaque/binary field
    485      * BinaryValue - the value of the field if this is an opaque/binary field
    486  * '''Return Values:'''
    487    * None
    488 
    489 When this succeeds the data will be passed into the testbed's vetting process.  The user will be notified out of band if the project was created.  Behind the scenes the project is created by an admin using {{{createProject}}} and this call is made on it by the admin:
    490 
    491  * '''Service:''' Projects
    492  * '''Operation:''' makeProjectVetting
    493  * '''Input Parameters:'''
    494    * Userid - the requester's userid
    495    * Name - the project's name
    496  * '''Return Values:'''
    497    * None
    498 
    499 And then the admin adds the requesting user to the project makes them owner and removes themselves.
     600   * Name - the new project's name
     601 * '''Return Values:'''
     602   * None
     603
     604Generally an removing a project requires a testbed administrator.
     605
     606
     607
    500608
    501609== Experiments ==