Introduction

This is the R Service Bus (RSB) API.

SOAP+MTOM API (Synchronous)

The RSB SOAP+MTOM API is fully described by its WSDL and the related XSDs.

REST API (Asynchronous)

The RSB REST API is documented below. Its micro-format is defined in the following XSDs for XML message definitions:

The JSON equivalents of these XML messages is built following the Jettison conventions as highlighted in this CXF documentation.

The REST API supports a set of HTTP headers:

Content-Type: required, defines the format of the data being sent by the client. Either application/json, application/xml or application/zip.
Accept: optional, defines the micro-format used by RSB when responding to a request. Either: application/vnd.rsb+xml or application/vnd.rsb+json (defaults to the former if absent).
X-RSB-Application-Name: required, a valid RSB application name (ie. must match this regular expression: /w+).
X-RSB-Meta-rScript and X-RSB-Meta-sweaveFile: standard optional job meta information parameters.
for custom job-specific meta information parameters, there are two possible specification types:
- (A) the parameter name is specified in the header field name (legacy method)
```
Field-Name: X-RSB-Meta-<ParameterName>`
Field-Value: <ParameterValue>`
```
  Note: since RSB 6.5 the parameter name is always converted to lower case; use specification type B for support of upper and mixed case names
- (B) the parameter is specified by a name-value pair in the header field value (since RSB 6.5)
```
Field-Name: X-RSB-Meta-#<Identifier>
Field-Value: <ParameterName>= <ParameterValue>`
```
  The identifier (e.g. a number) is required, in order that each HTTP header field name is unique; the identifier has no other meaning.

Any HTTP client that supports the GET, POST and DELETE verbs and HTTP headers can be used to interact with the REST API.

Example Interaction

This interaction will be done using the XML RSB micro-format. Only the significant HTTP headers are shown. Posting XML and JSON jobs is done the same way, only with different content types.

Posting a job

Request:

POST /rsb/api/rest/jobs HTTP/1.1
Content-Type: application/zip
X-RSB-Application-Name: testApp

...ZIP data...

Response:

HTTP/1.1 202 Accepted
Content-Type: application/vnd.rsb+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jobToken xmlns="http://rest.rsb.openanalytics.eu/types"
jobId="1f8c8aea-8d90-4bdf-92bb-b8da52f35e58"
applicationName="testApp"
submissionTime="2011-06-28T17:07:03.220Z"
applicationResultsUri="http://localhost:8888/rsb/api/rest/results/testApp"
resultUri="http://localhost:8888/rsb/api/rest/results/testApp/1f8c8aea-8d90-4bdf-92bb-b8da52f35e58"/>

The job token contains the necessary links to either browse all the jobs for the concerned application or to retrieve the result of the current job.

Retrieving a result

Request:

 GET /rsb/api/rest/results/testApp/1f8c8aea-8d90-4bdf-92bb-b8da52f35e58 HTTP/1.1

Response when the result is not ready:


HTTP/1.1 404 Not Found

Response when the result is ready:

HTTP/1.1 200 OK
Content-Type: application/vnd.rsb+xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<result xmlns="http://rest.rsb.openanalytics.eu/types"
jobId="1f8c8aea-8d90-4bdf-92bb-b8da52f35e58"
applicationName="testApp"
resultTime="2011-06-28T17:07:03.000Z"
success="true"
type="zip"
selfUri="http://localhost:8888/rsb/api/rest/results/testApp/1f8c8aea-8d90-4bdf-92bb-b8da52f35e58"
dataUri="http://localhost:8888/rsb/api/rest/result/testApp/1f8c8aea-8d90-4bdf-92bb-b8da52f35e58.zip"/>

As you can see, this is only the metadata for a result. The actual result data is reachable, with an HTTP GET, using the the provided data URI.

Deleting a result

Request:

 DELETE /rsb/api/rest/results/testApp/1f8c8aea-8d90-4bdf-92bb-b8da52f35e58 HTTP/1.1

Response:


HTTP/1.1 204 No Content

Browser Client

It is also possible to use the REST API from a browser, using a standard HTML form. In that case the following rules apply:

Content-Type must be multipart/form-data upload.
Accept: must be either application/xml or application/json (content sub-types are not well understood by browsers, hence the usage of the canonical XML and JSON types).
The X-RSB-* headers must be passed as form input field values named after the HTTP header they pass a value for.
File attachments must be passed as form input fields of type ‘file’ that must be named: X-RSB-JobFile[]