JSON-RPC in a nutshell
JSON-RPC is a well documented standard for webservices. It is like XML-RPC but instead of XML, the data exchange format is JSON (Java Script Object Notation).
- all requests are HTTP POST requests
- all requests look like this:
- without the id, the server gets notified but sends nothing back (only HTTP 200 OK but no data)
- all responses from the server return HTTP 200 OK - even when an error occured
- all responses return the same id as in the request
- because of this id, asynchronous communication is possible
- in case of a success, the response looks like this:
- in case of an error, the response looks like this:
In our examples below we use
"id" : "1" but of course, you should use a better id (e.g. the permId or something else which is unique)
We try to use openBIS v3 as often as possible. If no other information is given, all POST requests in our examples request the application server (AS) using the URL below. The typical port for the AS is 8443 (Change your hostname and your port number accordingly)
Not all methods have yet been implemented in the new v3 API. We sometimes need one of the following
The v1 JSCON API has many more endpoints which are described here
For requests regarding datasets on the datastore server (DSS), we have again different enpoints. The DSS usually runs on a different port, typically 8444. If we need datastore specific information (e.g. list of files) we need to use this endpoint:
You might have more than one DSS.
To play with the openBIS API (or any other webservice) I recommend using the Chrome plugin Postman. There is a (newer, shinier) Chrome App with the same name but I found its layout and readability not being as good.
Log in and out
Log into openBIS - get a token
Before you can request anythin from openBIS, you need to obtain a session token. Any subsequent request need this token.
You will get a response like this:
The string of the result is your session token. It contains your username, a dash '-' and an arbitary hexcode.
This token is always the first parameter value of any openBIS request.
Logout - destroy a session token
To end a session and destroy a session token, we use the
The response is as shown below. Because the result is null anyway, you could omit the
id in the request.
check if session token is valid
You can check whether your session is still valid by using the v1 API:
The 'result' of the response should contain
true if your session is still valid,
If your session token is invalid, any request will result in an error:
There are a number of methods to get information about our openBIS server. All information can be fetched in a similar way, by just changing the method name:
kind of information
If we have no special search criteria (just list them all), the typical request then looks like this:
working with Samples
The following methods requests data about a specific sample. Every sample is identified by an identifier and a permId.
get sample by identifier
To fetch a sample, we use the getSamples method and providing an identifier attribute together with a corresponding @type
get sample by permId
Fetching a sample by permId is done exactly the same way. Instead of an identifier we provide a permId attribute and a different @type:
create a sample
A sample needs a name (code), must be of a certain type (typeId), and must belong to a space (spaceID). It might contain specific properties as well as parents (parentIds), children (childIds) and many other connections.
If you want to specify one or more parents for that new sample, you need to specify it like this:
When you get a sample or any other openBIS entity, you often want to get some additional information along with the result, such as:
- its properties
- its parents
- its datasets
These informations can be obtained with additional fetch options, which can be nested, too:
The fetch options are the third (mandatory) parameter in your 'params' array. It may be an empty dictionary.
Here is an overview over all the possible fetch options and its type. Parents and childrens are usually of the same @type as the requested entity. This means, the parent of a sample is a parent too, the children of a
dataSet are dataSets too and so on.
name of entity
identical to the requested entity
identical to the requested entity
identical to the requested entity
Datasets are our links to the actual data, which is hosted on the datastore servers. Like samples,
datasets can have parents, children
Unlike samples, datasets only have a permId but not identifier. Its parents and containers
are datasets too, which means they are of the same @type.
get Dataset files
Finally we want to fetch the original files themselves. Our application server only hosts the metadata, not the original files. But it knows whom to ask. In the above example, we get back a lot of metadata, including 'dataStore'. This metadata object contains information about on which dataStore server our data is actually stored:
To actually fetch the list of files, we use the v1 API on the specified datastore server:
The argument list of 'params' is as follows:
- our session token
- the **permId of our dataset
- the folder to start with, usually '/' which means the root directory, '/start/here' if your starting point is somewhere else
- true = recursively look for all files in all subfolders; false = just get the list of the specified folder
This is the result we get back from the above query:
the 'isDirectory' flag indicates if whether the entry is a folder or not. Together with the earlier
information about our datastore server ('downloadUrl'), we are now able to actually download a file:
Uploading data is done in three steps:
- get the DSS URL
- upload the file(s) to the session workspace
- register the file(s) in openBIS
1. get available DSS
Before we can upload any data, we need to ask the application server (AS) which DSS are available. In many cases, we only have one DSS, but in some cases we can have more than one, so we have to choose. Fetching the list of available DSS done like this:
which gives you following result:
In our example we get two different datastores, and the attributes of our interest are downloadUrl which we need for the upload process and code which we need to initiate the registration process.
2. upload a file to the DSS
Now we have a choice of a DSS, we can start uploading a file. Our endpoint for uploading files:
In the URL we place the additional attributes:
all of the above attributes are mandatory. If you don't know the file size, you can just set
You need to include
Content-Type: multipart/form-data in your HTTP header in order to upload the file.
After successful upload, the response includes a status message, the filename and the size in bytes:
3. start data registration process
Once the file is uploaded to the user session workspace, we can initiate the data registration process. Every data file needs to be coupled to a dataset object which in turn needs to be connected to a sample. Without this important registration step, our file remains in the session workspace and gets deleted as soon as the session expires.
The registration process can be started by posting a request to our application server (AS):
This will start the dropbox my_dropbox_plugin (a Jython script which lives inside your DSS plugins folder) to look for files in our user session workspace and register them in openBIS. DSS2 is the code of the datastore server where we uploaded our file. The additional_parameters are sent to the
process method of our my_dropbox_plugin. These parameters typically include a sampleIdentifier, because all datasets need to be connected to a sample.