R Service Bus API

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 XSDs for XML message defintions. 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.
  • X-RSB-Meta-*: custom optional job-specific meta information parameters.

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[]

SOAP

This API is exposed through a set of WSI Basic Profile -compliant SOAP v1.1 endpoints. The API supports XML-binary Optimized Pacakging (XOP) and SOAP Message Transmission Optimization Mechanism (MTOM) for transmission of binary data. The SOAP API is fully described by the following endpoints:

The SOAP API is also accessible by client-side libraries that can be downloaded from the download page.

Data

All endpoints act on a common set of data. The data can be represented in different data formats (i.e. MIME types), depending on the endpoint that consumes and/or produces the data. The data can described by XML Schema, which definitively describes the XML representation of the data, but is also useful for describing the other formats of the data, such as JSON.

This document will describe the data using terms based on XML Schema. Data can be grouped by namespace, with a schema document describing the elements and types of the namespace. Generally speaking, types define the structure of the data and elements are instances of a type. For example, elements are usually produced by (or consumed by) a REST endpoint, and the structure of each element is described by its type.

Data Schemas

id namespace schema file
rest-data http://rest.rsb.openanalytics.eu/types rest-data.xsd
soap-data http://soap.rsb.openanalytics.eu/types soap-data.xsd

XML Data Elements

XML Data Types