The DETER testbed API is broken up into 5 services, each covering one of the major abstractions that the testbed exports. The services are:
We discuss each in detail and provide links to the detailed javadoc of the implementation, where applicable and available.
The document and API are both works in progress and will be fleshed out and changed as the API is modified.
The API is implemented as a SOAP web service over TLS secured connections. The user's identity is generally provided by a client certificate, but the client certificates are generally transient. A valid temporary client certificate can be requested from the API by correctly responding to a challenge keyed on the user's password.
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:
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.
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 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 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.
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.