Changes between Version 31 and Version 32 of NewTestbedAPISpec

Timestamp:

Jul 8, 2014 5:52:09 PM (10 years ago)

Author:

faber

Comment:

--

NewTestbedAPISpec

@@ -1013 +1013 @@
    A boolean, true if the aspect can be modified.
 
-Experiments also include an access control list (ACL) that lists the permissions that circles are granted to this experiment.
+Each experiment also includes an access control list (ACL) that lists the permissions that members of a given circle are granted to this experiment.
 
 [http://www.isi.edu/~faber/tmp/DeterAPI/doc/net/deterlab/testbed/api/Experiments.html experiments javadoc]
@@ -1230 +1230 @@
 === Manipulating Profile Attributes ===
 
-Administrators may add attributes to experiment profiles or remove them.  That is to say, add a schema (including format constraints and descriptions), not set a value for a project.
+Administrators may add attributes to experiment profiles or remove them.  That is to say, add a schema (including format constraints and descriptions), not set a value for an experiment.
 
 Creating an attribute:
@@ -1275 +1275 @@
  * '''Return Values:'''
   * a boolean, true if the attribute was created 
+
+
+== Libraries ==
+
+The library interface controls managing library contents. The experiment definition is in some flux, which is reflected in this section.
+
+An library is a collection of experiments, each of which can be manipulated by users with the proper permissions.  By grouping experiments it is easier to collaborate on the experiments as well as providing pools of experiments to use as starting points for new users.
+
+Each library includes an access control list (ACL) that lists the permissions that mebmers of a given circle are granted to the library.
+
+
+=== Viewing Libraries ===
+
+One or more libraried can be viewed by an authorized user assuming that user has the proper permissions.  The search can be a regular expression matched against the library name.  To view libraries, call:
+
+ * '''Service:''' Libraries
+ * '''Operation:''' viewLibraries
+ * '''Input Parameters:'''
+   * Userid - a string, if given return all experiments this user can see
+   * Regex - a string containing a regular expression matched against experiment names
+ * '''Return Values:'''
+   * One or more structures with the following fields
+     * Name - a string containing the experiment name
+     * Owner - a string containing the owner's userid
+     * Experiments - a list of experiment names 
+     * ACL - a list of structures of the form
+       * Name - a string the circle name
+       * Permissions - a list of strings containing this circle's permissions.  Permissions are from [http://www.isi.edu/~faber/tmp/DeterAPI/doc/constant-values.html#net.deterlab.testbed.api.Permissions this table]
+
+
+=== Creating and Deleting Libraries ===
+
+A library is created using:
+
+ * '''Service:''' Libraries
+ * '''Operation:''' createLibrary
+ * '''Input Parameters:'''
+   * Name - a string containing a new experiment's name
+   * Userid - the user making the request (the owner on success)
+   * Experiments - a list of experiments in the library
+   * AccessLists - a list of access list entries - a list of structures of the form
+       * Name - a string the circle name
+       * Permissions - a list of strings containing this circle's permissions.Permissions are from [http://www.isi.edu/~faber/tmp/DeterAPI/doc/constant-values.html#net.deterlab.testbed.api.Permissions this table] 
+   * Profile - a list of profile attribute value pairs
+ * '''Return Values:'''
+   * a boolean, true if the creation succeeded
+
+A library is deleted using:
+ 
+ * '''Service:''' Library
+ * '''Operation:''' removeLibrary
+ * '''Input Parameters:'''
+   * Name - a string containing the library to delete
+ * '''Return Values:'''
+   * a boolean, true on success
+
+After {{{removeLibrary}}} succeeds, library is removed from the testbed completely.
+
+=== Modifying Libraries ===
+
+Experiments can be added and removed from libraries
+
+* '''Service:''' Libraries
+ * '''Operation:''' addLibraryExperiment
+ * '''Input Parameters:'''
+   * Name - a string containing the library's name
+   * Experiments - a list of experiment names
+ * '''Return Values:'''
+   * a boolean, true if the addition succeeded
+
+As with creation, adding an aspect may result in additional sub-aspects appearing, as well as modifications to other aspects.
+
+* '''Service:''' Libraries
+ * '''Operation:''' removeLibraryExperiments
+ * '''Input Parameters:'''
+   * Name - a string containing the experiment's name
+   * Experiments - a list of experiments to remove
+ * '''Return Values:'''
+   * a boolean, true if the removal succeeded
+
+
+* '''Service:''' Libraires
+ * '''Operation:''' addLibraryACL
+ * '''Input Parameters:'''
+   * Name - a string containing the library's name
+   * AccessLists - a list of access list entries - a list of structures of the form
+       * Name - a string the circle name
+       * Permissions - a list of strings containing this circle's permissions.Permissions are from [http://www.isi.edu/~faber/tmp/DeterAPI/doc/constant-values.html#net.deterlab.testbed.api.Permissions this table]
+ * '''Return Values:'''
+   * a boolean, true if the removal succeeded
+
+* '''Service:''' Libraries
+ * '''Operation:''' removeLibraryACL
+ * '''Input Parameters:'''
+   * Name - a string containing the library's name
+   * AccessLists - a list circles to remove from the ACL
+ * '''Return Values:'''
+   * a boolean, true if the removal succeeded
+
+The owner can give ownership to another user.
+
+* '''Service:''' Library
+ * '''Operation:''' setOwner
+ * '''Input Parameters:'''
+   * Name - a string containing the experiment's name
+   * newOwner - a string, the new owner's UID
+ * '''Return Values:'''
+   * a boolean, true if the removal succeeded
+
+=== Library Profiles ===
+
+Libraries have profiles attached to them, as users, circles, and projects do.  Information in a profile is metadata about the library, intended for human consumption. 
+
+The calls for manipulating a library profile are very similar to other profiles:
+
+To get a profile schema, for example to create an empty web page,
+
+ * '''Service:''' Libraries
+ * '''Operation:''' getProfileDescription
+ * '''Input Parameters:'''
+ * '''Return Values:'''
+   * LibraryId - 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 string describing the access values (values [http://www.isi.edu/~faber/tmp/DeterAPI/doc/constant-values.html here])
+     * 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 library's profile.
+
+ * '''Service:''' Libraries
+ * '''Operation:''' getLibraryProfile
+ * '''Input Parameters:'''
+  * libid - a string naming the library to be retrieved
+ * '''Return Values:'''
+   * LibraryId - the experiment 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 string describing the access values (Defined [http://www.isi.edu/~faber/tmp/DeterAPI/doc/constant-values.html here])
+     * 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 library profile:
+ 
+ * '''Service:''' Libraries
+ * '''Operation:''' changeLibraryProfile
+ * '''Input Parameters:'''
+   * Libid - the library'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 library profiles or remove them.  That is to say, add a schema (including format constraints and descriptions), not set a value for a library.
+
+Creating an attribute:
+
+* '''Service:''' Libraries
+ * '''Operation:''' createLibraryAttribute
+ * '''Input Parameters:'''
+   * Name - the attribute name
+   * Type - the type (STRING, INT, FLOAT, OPAQUE)
+   * Optional - a boolean, true if this attribute is optional
+   * Access - a string: 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:''' Libraries
+ * '''Operation:''' removeLibraryAttribute
+ * '''Input Parameters:'''
+   * Name - the attribute name
+ * '''Return Values:'''
+  * a boolean, true if the attribute was removed 
+
+Finally administrators can modify profile attributes:
+
+* '''Service:''' Libraries
+ * '''Operation:''' modifyLibraryAttribute
+ * '''Input Parameters:'''
+   * Name - the attribute name
+   * Type - the type (STRING, INT, FLOAT, OPAQUE)
+   * Optional - a boolean, true if this attribute is optional
+   * Access - a string: 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 modified