Changes between Version 16 and Version 17 of NewTestbedAPISpec

Timestamp:

Aug 12, 2013 1:23:48 PM (11 years ago)

Author:

faber

Comment:

--

NewTestbedAPISpec

@@ -406 +406 @@
        * Userid - a member's userid
        * rights - a 32-bit integer encoding the user's rights (each a flag)
-         * ADD_USER - right to add a user to this group
-         * REMOVE_USER - right to remove a user from this group
-         * REALIZE_EXPERIMENT - the right to realize an experiment under this group
+         * ADD_USER - right to add a user to this project
+         * REMOVE_USER - right to remove a user from this project
+         * CREATE_CIRCLE - the right to create a circle under this project's name space
      * Approved - a flag indicating this project has been approved
 
@@ -685 +685 @@
 
 Generally an removing a project requires a testbed administrator.
+
+== Circles ==
+
+The profile API lets users manage their circle memberships as well as manipulate circles.  The circles API is similar to the Projects API.  The primary exceptions are that there is no approval process for circles (though there is for joining or adding a user) and that the permissions are different.
+
+These calls work on all circles '''except''' those linked to a project.  Those circles must have their membership, ownership, and permissions manipulated through the project to ensure that the contents remain synchronized.
+
+=== Listing Circles ===
+
+Authenticated users can look at the various circles they are members of, and may scope such searcher by circle names.
+
+ * '''Service:''' Circles
+ * '''Operation:''' viewCircles
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * Owner - a userid - only find circles owned by this user
+   * NameRE - a string containing a regular expression to match against circle names
+ * '''Return Values:'''
+   * A list of circle descriptors containing
+     * Name - a string contaiing the circle name
+     * Owner - the uid of the circle owner
+     * Members - an array of structures containing
+       * Userid - a member's userid
+       * rights - a 32-bit integer encoding the user's rights (each a flag)
+         * ADD_USER - right to add a user to this circle
+         * REMOVE_USER - right to remove a user from this circle
+         * REALIZE_EXPERIMENT - the right to realize an experiment under this circle
+
+Filters are cumulative: specifying a regular expression and an owner will match on both.
+
+=== Changing Circle Membership ===
+
+With appropriate rights a user can add another user to a circle they are in.
+The 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.
+
+ * '''Service:''' Circles
+ * '''Operation:''' addUsers
+ * '''Input Parameters:'''
+   * CircleID - the circle
+   * Uids - the userids to add
+   * Perms - the permissions to grant the user in this circle.  The values are given here.
+   * urlPrefix - a prefix to direct the user to a specific web interface to respond to the challenge.
+ * '''Return Values:'''
+   * A list of results of the form
+     * Name - the uid being added
+     * Success - a flag indicating success or failure
+     * Reason - the reason for a failure
+
+For each user successfully added, a notification is sent.  To respond to that notification the UI must call:
+
+* '''Service:''' Circles
+ * '''Operation:''' addUserConfirm
+ * '''Input Parameters:'''
+   * ChallengeID - the challenge being responded to
+ * '''Return Values:'''
+   * true if the user was added.  A fault is thrown on errors.
+
+Administrators can add users without going through the confirmation process:
+
+* '''Service:''' Circles
+ * '''Operation:''' addUsersNoConfirm
+ * '''Input Parameters:'''
+   * CircleID - the circle
+   * Uids - the userids to add
+   * Perms - the permissions to grant the user in this circle.  The values are given here.
+ * '''Return Values:'''
+   * A list of results of the form
+     * Name - the uid being added
+     * Success - a flag indicating success or failure
+     * Reason - the reason for a failure
+
+Users can also request to join a circle.  This requires some member of the circle with ADD_USER rights to agree, so a notification is sent to all such users.
+
+ * '''Service:''' Circles
+ * '''Operation:''' joinCircle
+ * '''Input Parameters:'''
+   * Uid - the uid to add
+   * CircleID - the circle to join
+   * urlPrefix - a prefix to direct the user to a specific web interface to respond to the challenge.
+ * '''Return Values:'''
+   * None
+
+The join succeeds when a user with appropriate permissions calls joinCircleConfirm.
+Note that the user calling joinCircleConfirm sets the new user's circle permissions.
+
+* '''Service:''' Circles
+ * '''Operation:''' joinCircleConfirm
+ * '''Input Parameters:'''
+   * ChallengeID - the challenge being responded to
+   * Perms - the permissions to grant the user in this circle.  The values are given here.
+ * '''Return Values:'''
+   * true if the user was subsequently added.  A fault is thrown on errors.
+
+
+Users can be removed from circles:
+
+ * '''Service:''' Circles
+ * '''Operation:''' removeUsers
+ * '''Input Parameters:'''
+   * CircleName - the circle to change
+   * Uids - uids to remove
+ * '''Return Values:'''
+   * A list of results of the form
+     * Name - the uid being added
+     * Success - a flag indicating success or failure
+     * Reason - the reason for a failure
+
+If a user has the right to both add and remove a user, that user can change a user's permissions:
+
+ * '''Service:''' Circles
+ * '''Operation:''' changePermissions
+ * '''Input Parameters:'''
+   * CircleName - the circle to change
+   * Uids - the uids to manipulate
+   * Rights - a 32-bit integer encoding the user's rights (each a flag)
+ * '''Return Values:'''
+   * A list of results of the form
+     * Name - the uid being added
+     * Success - a flag indicating success or failure
+     * Reason - the reason for a failure
+
+=== Manipulating Circles ===
+
+The owner of a group (and only the owner of that group) can give that privilege away to another member:
+
+ * '''Service:''' Circles
+ * '''Operation:''' setOwner
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * CircleName - the circle to change
+   * NewOwner - the uid of the new owner
+ * '''Return Values:'''
+   * None
+
+=== Circle Profiles ===
+
+The calls for manipulating a circle profile are very similar to user profiles:
+
+To get a profile schema, for example to create an empty web page,
+
+ * '''Service:''' Circles
+ * '''Operation:''' getProfileDescription
+ * '''Input Parameters:'''
+ * '''Return Values:'''
+   * Circleid - always empty
+   * A list of profile elements each containing
+     * Name - a string, the element's name
+     * DataType - a string giving the element's
+       * string
+       * integer
+       * double
+       * binary/opaque
+     * Value - a string containing the element's value
+     * 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])
+       * READ_WRITE
+       * READ_ONLY
+       * WRITE_ONLY (e.g., password)
+     * Optional - a flag true if the field is optional (must be present but may be empty)
+     * Removable - a flag true if the field can be removed
+     * Description - a string explaining the field
+     * Format - a regular expression that can be used to validate the field entry (may be null, and generally is for optional fields)
+     * FormatDescription - A brief, natural language description of the field input constraints, e.g. "A valid e-mail address" or "only numbers and spaces".
+     * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
+     * LengthHint - an integer suggesting how long an input firld should be presented
+
+To read a circle's profile.
+
+ * '''Service:''' Circles
+ * '''Operation:''' getCircleProfile
+ * '''Input Parameters:'''
+  * userid - a string naming the user to be retrieved
+ * '''Return Values:'''
+   * Circleid - the user whose profile is returned
+   * A list of profile elements each containing
+     * Name - a string, the element's name
+     * DataType - a string giving the element's
+       * string
+       * integer
+       * double
+       * binary/opaque
+     * Value - a string containing the element's value
+     * 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])
+       * READ_WRITE
+       * READ_ONLY
+       * WRITE_ONLY (e.g., password)
+     * Optional - a flag true if the field is optional (must be present but may be empty)
+     * Removable - a flag true if the field can be removed
+     * Description - a string explaining the field
+     * Format - a regular expression that can be used to validate the field entry (may be null, and generally is for optional fields)
+     * FormatDescription - A brief, natural language description of the field input constraints, e.g. "A valid e-mail address" or "only numbers and spaces".
+     * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
+     * LengthHint - an integer suggesting how long an input field should be presented
+
+Finally a user can modify a circle profile:
+
+ * '''Service:''' Circles
+ * '''Operation:''' changeCircleProfile
+ * '''Input Parameters:'''
+   * CircleId - the circle's profile to modify
+   * A list of change requests. Each request contains
+     * Name - the name of the field to change
+     * Value - the new value of the field
+     * Delete - a flag, if true delete the field rather than modify it
+ * '''Return Values:'''
+   * A list of responses each containing
+    * Name - astring with the name of the field
+    * Success - a flag indicating if the request succeeded
+    * Reason - a string indicating the reason if Success is false
+
+
+=== Manipulating Profile Attributes ===
+
+Administrators may add attributes to circle profiles or remove them.  That is to say, add a schema (including format constraints and descriptions), not set a value for a circle.
+Creating an attribute:
+
+* '''Service:''' Circles
+ * '''Operation:''' createCircleAttribute
+ * '''Input Parameters:'''
+   * Name - the attribute name
+   * Type - the type (STRING, INT, FLOAT, OPAQUE)
+   * Optional - a boolean, true if this attribute is optional
+   * Access - an integer the user's ability to modify (READ_WRITE, READ_ONLY, WRITE_ONLY, NO_ACCESS)
+   * Description - natural language description of the field (optional)
+   * Format - a regular expression describing the format (optional)
+   * Formatdescription - a natural language explanation of the format (optional)
+   * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
+   * LengthHint - an integer suggesting how long an input 
+   * Def - default value of the attribute (will be set for all users)
+ * '''Return Values:'''
+  * a boolean, true if the attribute was created 
+
+And removing an attribute:
+
+* '''Service:''' Circles
+ * '''Operation:''' removeCircleAttribute
+ * '''Input Parameters:'''
+   * Name - the attribute name
+ * '''Return Values:'''
+  * a boolean, true if the attribute was removed 
+
+Finally administrators can modify profile attributes:
+
+* '''Service:''' Circles
+ * '''Operation:''' modifyCircleAttribute
+ * '''Input Parameters:'''
+   * Name - the attribute name
+   * Type - the type (STRING, INT, FLOAT, OPAQUE)
+   * Optional - a boolean, true if this attribute is optional
+   * Access - an integer the user's ability to modify (READ_WRITE, READ_ONLY, WRITE_ONLY, NO_ACCESS)
+   * Description - natural language description of the field (optional)
+   * Format - a regular expression describing the format (optional)
+   * Formatdescription - a natural language explanation of the format (optional)
+   * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
+   * LengthHint - an integer suggesting how long an input
+ * '''Return Values:'''
+  * a boolean, true if the attribute was created
+
+
+=== Creating and Deleting Circles ===
+
+Creating and removing circles are also similar to creating and removing users:
+
+ * '''Service:''' Circles
+ * '''Operation:''' createCircle
+ * '''Input Parameters:'''
+   * CircleId - the new circle's name
+   * Uid - the new owner's uid (usually the caller)
+   * profile - a list of attributes that will make up the circle's profile
+   * A list of profile elements each containing
+     * Name - a string, the element's name
+     * StringValue - a string containing the element's value
+ * '''Return Values:'''
+   * None
+
+As with users, all required (non-optional) fields in the profile must be provided.  The circle will be created, and can be used immediately.
+
+Removing a circle is straightforward.
+
+ * '''Service:''' Circles
+ * '''Operation:''' removeCircle
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * Name - the new circle's name
+ * '''Return Values:'''
+   * None
 
 == Experiments ==