Changes between Version 1 and Version 2 of NewTestbedAPISpec

Timestamp:

Jun 26, 2013 5:47:20 PM (11 years ago)

Author:

faber

Comment:

--

NewTestbedAPISpec

@@ -19 +19 @@
 The API is implemented using the axis web service framework, which means that javadocs are provided for the various calls.
 
+Each service and call are accessed by appending servicename/operation to the base URL of the API server.  On DETERlab the base URL will be https://api.isi.deterlabnet:52323/axis2/service.  For example, one can access the getVersion operation below at https://api.isi.deterlabnet:52323/axis2/service/ApiInfo/getVersion 
+
+Each operation returns useful parameters on success and throws a fault, called a DeterFault, on an error.  Faults are standard SOAP faults with a detail section that includes the following fields:
+
+ * ErrorCode - a 32-bit integer encoding the type of error.  Constants are available in the [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/api/DeterFault.html javadoc for DeterFault].  Values are:
+   * access - access denied
+   * request - bad request
+   * internal - internal server error
+ * ErrorString - a string describing the broad error
+ * DetailString - a string describing the details that caused the error
+
+The {{{ErrorString}}} and {{{ErrorCode}}} are equivalent, but the information in the {{{DetailString}}} is generally more informative about the specifics.  Request or access errors are generally correctable on the client side while internal errors are not.
+
+[http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/api/DeterFault.html javadoc for DeterFault]
+
 == ApiInfo ==
 
 The ApiInfo service provides metadata about the running DETER API.  It also provides a simple check that a user is presenting authentication credentials correctly.
 
-The sole call in the ApiInfo service is {{{getVersion}}}, available at https://api.isi.deterlab.net:52323/axis2/services/ApiInfo/getVersion .  It takes no arguments and returns
+[http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/api/ApiInfo.html javadoc for ApiInfo]
 
- Version::
-  A string containing the API version number
- 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.
+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.
 
-[http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/api/ApiInfo.html javadoc]
+ * '''Service:''' ApiInfo
+ * '''Operation:''' getVersion
+ * '''Input Parameters:'''
+   * None
+ * '''Return Values:'''
+   * Version - A string containing the API version number
+   * 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.
 
 == Users ==
@@ -38 +55 @@
 The Users API is concerned with managing users and their profiles as well as authenticating to the testbed and receiving a client certificate for later calls.
 
+[http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/api/Users.html javadoc for Users]
+
+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.
+
+Currently only one challenge type is defined.  The challenge is an array of bytes and the response is return an SHA1 HMAC of that string keyed by the user's password.
+
+ * '''Service:''' Users
+ * '''Operation:''' requestChallenge
+ * '''Input Parameters:'''
+   * userid - the identity to authenticate
+ * '''Return Values:'''
+   * Type - the kind of challenge
+   * Data - the data needed for the challenge
+   * Validity - number of seconds the challenge may be responded to
+   * ChallengeID - a 64-bit identifier that allows the server to validate the reply
+
+ * '''Service:''' Users
+ * '''Operation:''' challengeResponse
+ * '''Input Parameters:'''
+  * ResponseData - a binary string, the response to the challenge
+  * ChallengeID - The 64-bit identifier of the challenge being responded to
+ * '''Return Values''':
+  * Certificate - a binary string containing a PEM-encoded X.509 certificate and private key. (Passed down the encrypted connection)
+
+
+
+