Changes between Version 5 and Version 6 of NewTestbedAPISpec

Timestamp:

Jun 28, 2013 4:46:53 PM (11 years ago)

Author:

faber

Comment:

--

NewTestbedAPISpec

@@ -42 +42 @@
 [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/api/ApiInfo.html javadoc for ApiInfo]
 
-The sole operation in the ApiInfo service is {{{getVersion}}}.  The call is unauthenticated and can be made driectly from a web browser to confirm that the API is functioning and that the user can see DETERlab.
+The primary operation in the ApiInfo service is {{{getVersion}}}.  The call is unauthenticated and can be made driectly from a web browser to confirm that the API is functioning and that the user can see DETERlab.
 
  * '''Service:''' ApiInfo
@@ -52 +52 @@
    * PatchLevel - A string containing the patch level
    * KeyID - A string.  If the user presented a valid public key and passed the challenge, this is the sha1 hash of that key.  If no key was presented or an invalid one, this filed is not returned.
+
+There is an addtional simpler service, {{{echo}}}, that takes one parameter and returns it:
+
+ * '''Service:''' ApiInfo
+ * '''Operation:''' echo
+ * '''Input Parameters:'''
+   * param - a string to echo
+ * '''Return Values:'''
+   * the same string
 
 == Users ==
@@ -522 +531 @@
 
 After {{{releaseExperiment}}} succeeds, experiment state remains in the testbed, but containers are stopped and resources are returned to the testbed.
+
+== Resources ==
+
+Resources are things that make up experiments.  There are several specialized resources used in experimentation that have their own suite of operations, and there is a general set of operations for future expansion.
+
+=== Computers ===
+
+Computers are the physical computing resources of the testbed.  A user may be interested in specific instances of a computer - {{{pc23}}} - or in information about types or classes of computers.  Both are possible to view with these calls.
+
+A user can view computers or classes by:
+
+ * '''Service:''' Resources
+ * '''Operation:''' viewComputers
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Owner - an optional string the computer owner
+   * NameRE - an optional string containing a regular expression matched against the name
+   * Type - an optional string containing the computer types to look for
+ * '''Return Values:'''
+   * Zero or more structures with the following fields:
+     * Name - a string, the name of this computer, if absent this is a class
+     * Owner - a string, the owner of the computer or class
+     * Type - a string containing the type of computer
+     * Description - a string describing this computer or class
+     * Allocated - an optional flag indicating whether this computer is allocated.  The field is absent all together if this structure describes a class
+     * AllocatedExperiment - an optional string containing the experiment name if the computer is allocated and the user has the right to read the experiment
+     * AllocatedProject - an optional string containing the project name in which the experiment is realized if the computer is allocated and the user has the right to read the project
+     * ProjectDelete - an optional list of project names that can delete this resource
+     * ProjectModify - an optional list of project names that can modify this resource
+     * ProjectUse - an optional list of project names that can use this resource
+     * ProjectRead - an optional list of projects names that can read this resource
+
+If any of the permission fields are not present, the class permissions apply.  If they are present for a specific computer, they specific computer's permissions override the class permissions.
+
+Administrators can add new computers or classes using
+
+ * '''Service:''' Resources
+ * '''Operation:''' createComputer
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Name - an optional string, the name of this computer, if absent this is a class
+   * Type - a string containing the type of computer
+   * Description - an optional string describing this computer or class (If omitted for a computer, the type description is used)
+   * ProjectDelete - an optional list of project names that can delete this resource
+   * ProjectModify - an optional list of project names that can modify this resource
+   * ProjectUse - an optional list of project names that can use this resource
+   * ProjectRead - an optional list of projects names that can read this resource
+ * '''Return Values:'''
+   None
+
+Note that missing fields in a computer creation are generally filled in from the type.  Creating a computer or class without any projects that can use it is of questionable value.
+
+Similarly, they can modify an existing computer using (assuming they are in a project that allows modification of the class or computer):
+
+ * '''Service:''' Resources
+ * '''Operation:''' modifyComputer
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Name - an optional string, the name of this computer, if absent this is a class
+   * Type - an optional string containing the type of computer
+   * Description - an optional string describing this computer or class (If omitted for a computer, the type description is used)
+   * ProjectDelete - an optional list of project names that can delete this resource
+   * ProjectModify - an optional list of project names that can modify this resource
+   * ProjectUse - an optional list of project names that can use this resource
+   * ProjectRead - an optional list of projects names that can read this resource
+ * '''Return Values:'''
+   None
+
+Values passed in overwrite the current values if the user had modify rights.  One of Name or Type must be present.
+
+Finally an administrator can delete a computer:
+
+ * '''Service:''' Resources
+ * '''Operation:''' removeComputer
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Name - an optional string, the name of this computer, if absent this is a class
+   * Type - an optional string, the type of computer.  May be omitted for specific computers
+ * '''Return Values:'''
+   None
+
+=== Images ===
+
+Images are saved container state - including saved physical container state.  These are selected in the experiment definition, but users may need to manipulate them directly.
+
+To read image information:
+
+ * '''Service:''' Resources
+ * '''Operation:''' viewImages
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Owner - an optional string the computer owner
+   * NameRE - an optional string containing a regular expression matched against the name
+ * '''Return Values:'''
+   * Zero or more structures with the following fields:
+     * Name - a string, the name of this image
+     * Owner - a string, the owner of the image
+     * Description - a string describing this image
+     * ValidIn - a list of container types that can use this image
+     * ProjectDelete - a list of project names that can delete this resource
+     * ProjectModify - a list of project names that can modify this resource
+     * ProjectUse - a list of project names that can use this resource
+     * ProjectRead - a list of projects names that can read this resource
+
+Images are created by operations on a container, but users can modify or delete their metadata:
+
+ * '''Service:''' Resources
+ * '''Operation:''' modifyImage
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Name - a string, the name of this image
+   * Description - an optional string describing this computer or class
+   * ValidIn - an optional list of container types that can use this image
+   * ProjectDelete - an optional list of project names that can delete this resource
+   * ProjectModify - an optional list of project names that can modify this resource
+   * ProjectUse - an optional list of project names that can use this resource
+   * ProjectRead - an optional list of projects names that can read this resource
+ * '''Return Values:'''
+   None
+
+
+As with other resources, these values overwrite the existing parameters (except for name which is a selector).
+
+A user can delete an image:
+
+ * '''Service:''' Resources
+ * '''Operation:''' removeImage
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Name - a string, the image to remove
+ * '''Return Values:'''
+   None
+
+
+=== Pubkey ===
+
+Public/Private keypairs are used several places in the testbed for authentication and access.  For example, access to containers that present a computer interface is done using the ssh protocol.  These interfaces allow users to manipulate their keys.
+
+Viewing keys:
+
+* '''Service:''' Resources
+ * '''Operation:''' viewKeys
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Owner - an optional string the computer owner
+   * type - an optional string containing the kind of keys to report
+ * '''Return Values:'''
+   * Zero or more structures with the following fields:
+     * Name - a string, the name of this key
+     * Owner - a string, the owner of the key
+     * Description - a string describing this key
+     * KeyData - an opaque data value - the key data
+     * ProjectDelete - a list of project names that can delete this resource
+     * ProjectModify - a list of project names that can modify this resource
+     * ProjectUse - a list of project names that can use this resource
+     * ProjectRead - a list of projects names that can read this resource
+
+
+Users can add and delete keys:
+
+* '''Service:''' Resources
+ * '''Operation:''' addKey
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Owner - an optional string the computer owner
+   * Name - an optional string, the name of this key (system will assign if omitted)
+   * Description - an optional string describing this key
+   * KeyData - an opaque data value - the key data
+   * ProjectDelete - a list of project names that can delete this resource
+   * ProjectModify - a list of project names that can modify this resource
+   * ProjectUse - a list of project names that can use this resource
+   * ProjectRead - a list of projects names that can read this resource
+ * '''Return Values:'''
+   * None
+
+ * '''Service:''' Resources
+ * '''Operation:''' removeKey
+ * '''Input Parameters:'''
+   * Userid - the user making the request
+   * Name - a string, the name of this key