Changes between Version 32 and Version 33 of NewTestbedAPISpec

Timestamp:

May 1, 2015 4:54:08 PM (10 years ago)

Author:

faber

Comment:

--

NewTestbedAPISpec

@@ -9 +9 @@
  * Users
  * Projects
- * Resources
  * Experiments
  * Libraries
+ * Resources
+ * Realizations
 
 We discuss each in detail and provide links to the detailed javadoc of the implementation, where applicable and available.
@@ -1730 +1731 @@
 Users can add and delete keys:
 
-* '''Service:''' Resources
+ * '''Service:''' Resources
  * '''Operation:''' addKey
  * '''Input Parameters:'''
@@ -1750 +1751 @@
    * Userid - the user making the request
    * Name - a string, the name of this key
+
+== Realizations ==
+
+A realization is a binding of an Experiment and a Circle to Resources.  Intuitively, it is an experiment in progress.  A researcher manipulates a realization using the Realizations service.
+
+=== Viewing Realizations ===
+
+One or more realizations - experiments in progress - can be viewed by an authorized user assuming that user has the proper permissions.  The search can be scoped by circle, and a regular expression matched against the experiment name.  To view realizations, call:
+
+ * '''Service:''' Realizations
+ * '''Operation:''' viewRealizations
+ * '''Input Parameters:'''
+   * Userid - a string, if given return all experiments this user can see
+   * Circle - a string, the name of a circle.  Only experiments realized in that circle will be returned
+   * 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 realization name (scoped by owner name)
+     * Owner - a string containing the owner's userid
+     * Circle - the circle that the experiment is realized in
+     * State - one of:
+       * initializing
+       * changing
+       * active
+       * terminating
+     * Mapping - a list of structures of the format
+       * Element name - the name of the element from the experiment's layout aspect
+       * Resource name - the name of the resource to which the element is mapped
+
+
+=== Creating A Realization ===
+
+A researcher creates a realization - starts an experiment - using the realizeExperiment operation.
+
+ * '''Service:''' Realizations
+ * '''Operation:''' realizeExperiment
+ * '''Input Parameters:'''
+   * Userid - the user making the request (the owner on success)
+   * Owner - an optional string the computer owner
+   * Circle - the circle under which the experiment is being created
+   * Experiment - the experiment being realized
+   * Name - an optional string, the name of this realization (system will assign if omitted) - scoped by owner name
+ * '''Return Values:'''
+   * Success or failure
+
+Though none are yet specified, constraint aspects on the experiment may influence the realization.
+
+
+