Xmlrpcinterface
XMLRPC Interface
All ProtoGENI authorities (i.e. the Clearing House, Component Manager, Slice Authority and Slice Embedding Service) present an XMLRPC interface to clients over HTTP and SSL. Each service has a single URL registered with the Clearing House, and all requests are made via that address.
Both the client and server must authenticate during connection setup. Each member of the federation has a self-signed X.509 certificate, and this set of certificates is distributed by the Clearing House. Since each site is assumed to hold the complete set of certificates and revocation lists, this infrastructure is sufficient for each party to validate the identity of the other. (However, this SSL level authentication does not resolve issues of permission and privilege, which are left to higher layers: typically addressed with credential parameters to appropriate RPC operations.)
XMLRPC Request
Other than the SSL requirements mentioned above, the XMLRPC request is a simple methodCall structure as described in the XMLRPC specification. The methodName and params values are described on the API documentations for each service.
XMLRPC Response
Unlike the requests, ProtoGENI XMLRPC responses are somewhat stylised and follow a number of conventions.
Response structure
All responses from the server must return HTTP code 200, and a methodResponse structure with a single params child, even in the case of ProtoGENI errors. HTTP error codes and XMLRPC fault responses are reserved for lower level errors.
Response parameters
The params XML element must always contain exactly three children:
code
All responses contain a code value, of type int. This is used to indicate either the successful result of an operation, or a machine-readable indication of what went wrong. Unless otherwise specified, any unsuccessful operations (those with codes other than 0 or 16) have no side effects.
The values currently defined for code are:
- 0
- GENIRESPONSE_SUCCESS
- 1
- GENIRESPONSE_BADARGS
- 2
- GENIRESPONSE_ERROR
- 3
- GENIRESPONSE_FORBIDDEN
- 4
- GENIRESPONSE_BADVERSION
- 5
- GENIRESPONSE_SERVERERROR
- 6
- GENIRESPONSE_TOOBIG
- 7
- GENIRESPONSE_REFUSED
- 8
- GENIRESPONSE_TIMEDOUT
- 9
- GENIRESPONSE_DBERROR
- 10
- GENIRESPONSE_RPCERROR
- 11
- GENIRESPONSE_UNAVAILABLE
- 12
- GENIRESPONSE_SEARCHFAILED
- 13
- GENIRESPONSE_UNSUPPORTED
- 14
- GENIRESPONSE_BUSY
- 15
- GENIRESPONSE_EXPIRED
- 16
- GENIRESPONSE_INPROGRESS
value
The value parameter, when present, yields the result of the ProtoGENI operation. It can be of any valid XMLRPC type (including struct and array), and is specified in the documentation for individual RPC calls. Unless otherwise documented, it is not defined in cases of error.
output
Whenever code indicates an error, a human-readable description of the problem is provided in the output field (of type string). User agents are expected to make this text available to the user.
output is generally not provided when operations complete successfully.