JSON-RPC

The CLOUDFLOW API uses JSON-RPC to communicate with the back end, a remote procedure call protocol which uses HTTP as the transport protocol and JSON as the encoding.

All calls are handled by portal.cgi, so in order to use the API in another application, you have to send a JSON object to portal.cgi. This will establish a data connection during which you can invoke API methods.

All API calls are handled by portal.cgi, which is accessible through ​​http://<server>:<port>/portal.cgi.

To invoke a remote method, you need to send an API request which is replied to with a response.

Request

To invoke a method, you need to send a request to portal.cgi. A request is a single JSON object and contains the following properties:
  • The method ('method'): the method name.
  • Parameters ('param'): the parameters.

It looks like this:

{
'method'  : 'method name',
'param 1' : 'the first parameter',
'param 2' : 'the second parameter'
...
}

Response

After the method has been invoked, the service sends a response. A response is also a single JSON object and contains the following properties:
  • The result ('result'): the returned object.
In case of an error when invoking the method, the service returns an error object with the following fields:
  • 'error_code': a category code ('generic' in most cases).
  • 'error': the error description (usually for debugging purposes).
The following 'error_codes' are typically used:
  • 'generic': a generic error.
  • 'invalid_session': the session code is invalid or the session has expired.
  • 'no_license': the required license is not activated on the machine.
  • 'no_permission': the user doesn't have permission to call the method with the supplied parameters.
  • 'unknown_command': the method identifier is not recognized by the server.

Parameters for authentication and session

For authentication reasons the JSON object requires at least the following parameters:
  • 'session': the session ID.
    To invoke a method, the application first needs to obtain a session ID. You can create a session ID by invokingauth.create_session. This call requires the following parameters:
    • method: auth.create_session.
    • user_name: the user name.
    • user_pass: the password.

    If the call is successful, the server returns a JSON object with a 'session' field. If it fails, the return value is a error of type 'generic'.

    A session is valid for 12 hours.

  • 'session_scope': an optional parameter indicating the user scope. The default value is *. If the user has only one scope, the parameter is ignored.
  • 'method': the name of the method to invoke, in form 'module.method' (for example 'proofscope.create_url').