Changes between Version 2 and Version 3 of NewTestbedAPISpec

Timestamp:

Jun 26, 2013 6:16:48 PM (11 years ago)

Author:

faber

Comment:

--

NewTestbedAPISpec

@@ -57 +57 @@
 [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/api/Users.html javadoc for Users]
 
+=== Authentication ===
+
 A user can authenticate to the testbed and receive a short-lived client x.509 certificate by requesting a challenge using the {{{requestChallenge}}} operation and responding to the challenge via the {{{challengeResponse}}} operation.
 
@@ -79 +81 @@
   * Certificate - a binary string containing a PEM-encoded X.509 certificate and private key. (Passed down the encrypted connection)
 
+=== Profile Manipulation ===
 
+DETER keeps metadata about each user called a profile.  The API provides an authenticated user with several interfaces to query and modify their profile information.
 
+In the API each element of profile data is represented as a structure with the following data in it:
 
+ * name of the element
+ * type of the element
+  * string
+  * integer
+  * double
+  * binary/opaque
+ * value(s) of the element
+ * a flag set if the element is optional
+ * A flag set if the field can be removed from the profile
+ * a modification type: elements may be read/write, read-only (e.g., username) or write-only (e.g., password)
+ * a brief description of the field, intended to be presented by a web interface or other third party program
+
+To get a profile schema, for example to create an empty web page,
+
+ * '''Service:''' Users
+ * '''Operation:''' getProfileDescription
+ * '''Input Parameters:'''
+ * '''Return Values:'''
+   * Uid - 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
+     * 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
+     * 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
+
+To read a user's profile (generally only users can read their own profile).
+
+ * '''Service:''' Users
+ * '''Operation:''' getProfileDescription
+ * '''Input Parameters:'''
+  * userid - a string naming the user to be retrieved
+ * '''Return Values:'''
+   * Userid - 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
+     * 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
+     * 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
+
+Finally a user can modify a profile:
+ 
+ * '''Service:''' Users
+ * '''Operation:''' getProfileDescription
+ * '''Input Parameters:'''
+   * Userid - the user's profile to modify
+   * A list of change requests. Each request contains
+     * Name - the name of the field to change
+     * StringValue - the new value of the field if this is not an opaque/binary field
+     * BinaryValue - the new value of the field if this is an opaque/binary 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
+
+=== Creation ===
+
+Finally a user can request access to the testbed by creating a profile.  The user has no privileges and consumes minimal resources until they join a vetted project.  This is an unauthenticated call, but the user profile is not created until an automated e-mail exchange is made between the testbed and the proto-user.
+
+ * '''Service:''' Users
+ * '''Operation:''' getProfileDescription
+ * '''Input Parameters:'''
+   * Userid - the requested userid
+   * A list of profile elements each containing
+     * Name - a string, the element's name
+     * StringValue - a string containing the element's value, unless it is binary/opaque
+ * '''Return Values:'''
+  * None
+
+Note that all non-optional fields must be provided, so this is best preceeded by a call to getProfileDescription to learn the fields.