Changes between Version 3 and Version 4 of NewTestbedAPISpec

Timestamp:

Jun 27, 2013 12:00:25 PM (11 years ago)

Author:

faber

Comment:

--

NewTestbedAPISpec

@@ +1 @@
+[[TOC]]
+
 = DETER Testbed API =
 
@@ -165 +167 @@
     * Reason - a string indicating the reason if Success is false
 
+=== Notifications ===
+
+A notification is a short message from another user or the testbed asking a user to take an action (add someone to a project, update a password before expiration) or communicating other information to the user (testbed downtime, etc).  A web interface will want to present these to a user.
+
+ 
+ * '''Service:''' Users
+ * '''Operation:''' getNotifications
+ * '''Input Parameters:'''
+   * Userid - the user's identity to gather notifications
+   * FirstDate - an optional date.  If present only show notifications after that date
+   * LastDate - an optional date.  If present only show notifications before that date
+   * OnlyUnread - a flag. If true, show only unread notifications
+ * '''Return Values:'''
+   * A list of responses each containing
+     * ID - a 64-bit integer identifying the notification
+     * IsRead - a flag indicating that the message has been read by this user
+     * Sent - the date the notification was issued
+     * Text - the text of the notification
+
+The filtering variables are all applied if given.  If OnlyUnread is true and FirstDate and LastDate are both given, only unread notifications between those dates are returned.
+
+ * '''Service:''' Users
+ * '''Operation:''' markNotificationsRead
+ * '''Input Parameters:'''
+   * Userid - the user's identity to gather notifications
+   * Notifications - an array of 64-bit integers, the notifications to mark read
+ * '''Return Values:'''
+   * None
+
 === Creation ===
 
@@ -180 +211 @@
 
 Note that all non-optional fields must be provided, so this is best preceeded by a call to getProfileDescription to learn the fields.
+
+== Projects ==
+
+The profile API lets users manage their project memberships as well as manipulate projects.
+
+=== Listing Projects ===
+
+Authenticated users can look at the various projects they are members of, and may scope such searcher by project names.
+
+ * '''Service:''' Projects
+ * '''Operation:''' viewProjects
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * Owner - a userid - only find projects owned by this user
+   * NameRE - a string containing a regular expression to match against project names
+ * '''Return Values:'''
+   * A list of project descriptors containing
+     * Name - a string contaiing the project name
+     * 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 group
+         * REMOVE_USER - right to remove a user from this group
+         * REALIZE_EXPERIMENT - the right to realize an experiment under this group
+     * Vetting - a flag indicating this is a vetting project
+
+Filters are cumulative: specifying a regular expression and an owner will match on both.
+
+== Manipulating Projects ==
+
+With appropriate rights a user can add another user to a project they are in:
+
+ * '''Service:''' Projects
+ * '''Operation:''' addUser
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * ProjectName - the project to change
+   * NewUser - the uid to add to the group
+ * '''Return Values:'''
+   * None
+
+If this fails, a fault is sent.  A call to {{{viewProjects}}} will confirm the change.
+
+Similarly, a user can be removed:
+
+ * '''Service:''' Projects
+ * '''Operation:''' removeUser
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * ProjectName - the project to change
+   * RemoveUser - the uid to remove from the group
+ * '''Return Values:'''
+   * None
+
+If a user has the right to both add and remove a user, that user can change a user's permissions:
+
+ * '''Service:''' Projects
+ * '''Operation:''' changePermissions
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * ProjectName - the project to change
+   * TargetUser - the uid to manipulate
+   * 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
+ * '''Return Values:'''
+   * None
+
+The owner of a group (and only the owner of that group) can give that privilege away:
+
+ * '''Service:''' Projects
+ * '''Operation:''' setOwner
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * ProjectName - the project to change
+   * NewOwner - the uid of the new owner
+ * '''Return Values:'''
+   * None
+
+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.
+
+ * '''Service:''' Projects
+ * '''Operation:''' requestJoin
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * ProjectName - the project to join
+ * '''Return Values:'''
+   * None
+
+=== Manipulating Projects ===
+
+Non-vetting projects can be created and deleted with little overhead:
+
+ * '''Service:''' Projects
+ * '''Operation:''' createProject
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * Name - the new project's name
+ * '''Return Values:'''
+   * None
+
+On success the new project is created with the calling user as owner and sole member.  The user has all rights.
+
+ * '''Service:''' Projects
+ * '''Operation:''' removeProject
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * Name - the new project's name
+ * '''Return Values:'''
+   * None
+
+Generally an owner can remove a project, but removing a vetting project requires a testbed administrator.
+
+Because creating a vetting project may require review, it is more involved.  First the user retrieves the testbed's schema for information to supply:
+
+ * '''Service:''' Projects
+ * '''Operation:''' getVettingRequirements
+ * '''Input Parameters:'''
+ * '''Return Values:'''
+   * A list of requirements elements each containing
+     * Name - a string, the element's name
+     * DataType - a string giving the element's
+       * string
+       * integer
+       * double
+       * binary/opaque
+     * StringValue - a string containing the element's value, unless it is binary/opaque
+     * BinaryValue - a byte string containing the element's value if it is binary/opaque
+     * Optional - a flag true if the field is optional (must be present but may be empty)
+     * Description - a string explaining the field
+
+A web interface will gather this interface and call:
+
+ * '''Service:''' Projects
+ * '''Operation:''' createVettingProject
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * Name - a string containing the project name
+   * A (possibly empty) list of vetting info fields requests. Each request contains
+     * Name - the name of the field supplied
+     * StringValue - the value of the field if this is not an opaque/binary field
+     * BinaryValue - the value of the field if this is an opaque/binary field
+ * '''Return Values:'''
+   * None
+
+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:
+
+ * '''Service:''' Projects
+ * '''Operation:''' makeProjectVetting
+ * '''Input Parameters:'''
+   * Userid - the requester's userid
+   * Name - the project's name
+ * '''Return Values:'''
+   * None
+
+And then the admin adds the requesting user to the project makes them owner and removes themselves.