[[TOC]]

= DETER Testbed API =

This is the beginning of the living document that will document the DETER testbed API>

== User Features ==

A '''user''' is a researcher who uses the DETER testbed.  They request testbed services and allocate testbed resources.  Each call on the API is performed by a user.  A user is identified by a string unique to DETER, teh username.

=== User Meta-data ===

In addition to the user identifier DETER keeps meta-data about all users.  Currently that meta-data consists of:

 * Projects the user is in (see below)
 * Experiments the user owns (see below)
 * A password to authenticate the user
 * A valid e-mail address for communication and password resetting
 * Resource access information, e.g., 
   * ssh public keys
   * windows authentication credentials
 * General metadata, e.g, 
   * Real name
   * Affiliation
   * Phone number
   * Address

The API provides an authenticated user (see below) 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
  * lists of any of the above
 * value(s) of the element
 * a flag set if the element is optional
 * 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

The interfaces to manipulate a profile are

 * '''GetProfileDescription'''
   * No input required
   * Returns a set of empty elements that this testbed understands and requires, represented as above
 * '''GetUserProfile'''
   * No input required execpt an authenticated user
   * Returns a populated set of elements containing the current values of the user's profile
 * '''SetUserProfile'''
   * A list of populated elements that the (authenticated) user wishes to change in the current profile
   * A list of the elements successfully updated, and a list of those that failed with a reason for each


=== Authenticating as a User ===

A user represnts themself to the testbed by presenting proof that they hold a public key, for example through an SSL connection.  The testbed determines what operations a user can carry out based on an ABAC-encoded policy that grants rights to users and binds keys to users.  A user is issued a public key periodically by DETER, but also can request a short lived temporary key at any time by authenticating against a shared password.  A temporary key is useful to allow a web application or other hosted tool to act on a user's behalf.