Introduction

As part of the IRCT we have created a simple but powerful RESTFull API that can be used to communicate with any number of servers. Below is a list of available calls and basic information about these services. To learn more about the IRCT click here or to download our documentation here.

Security

The IRCT provides a secure way of accessing patient data across multiple resources. It does not store any passwords, and itself does not do any authentication of which resources the user has access to. By not implementing any specific authentication mechanism it avoids the need for resources to conform to the same access restrictions. It also keeps the governance for individual access to be defined by the resources themselves. It does require that all resources that have access restrictions use the same identity service provider. This identity service provider may access other identity stores. The identity service provider must support OpenID Connect and all connections should be secured using HTTPS.

/rest/v1/securityService/createState

This call returns a randomly generated number that is used to ensure a secure connection

/rest/v1/securityService/createKey

This call creates an IRCT key for secure access outside of a browser

/rest/v1/securityService/callback

This is called by the open ID provider to authenticate the user

Parameter Description
CODE required Authorization code from the identity provider
STATE required State identity originally created by the IRCT
ERROR optional An error message that occurred while authenticating the user
/rest/v1/securityService/startSession

This call is used to create a secure session outside of a browser

Parameter Description
KEY required IRCT access key
/rest/v1/securityService/endSession

Ends a secure session

Resource

A resource can be considered anything that provides data, or processing methods to an end user. This broad definition allows the IRCT to communicate with many different types of services. As stated before it does not require the resource to conform to any specific protocol, or ontology. This means a resource can be as simple as a file, or as complicated as an i2b2 instance. The resources can exist anywhere from being hosted on the same server, to being hosted behind a firewall in another institution.

Resources define what they are, and what they can do through the IRCT. This includes information about what data types that they support as well as what actions such as queries or processes they may perform. These actions define how an end user uses the IRCT to interact with them. This allows for a single protocol and server to be used to communicate with any number of resources of any number of types. How the different actions are defined, and used are defined in their respective sections of this documentation.

/rest/v1/resourceService/resources

This call is used to return a list of all available resources. The default behavior is to return all resources, but filtering can by specifying the type of resources

Parameter Description
TYPE optional Type of resource e,g, Process, Query, Visualization
/rest/v1/resourceService/path

This call is used to traverse the relationships of different entities of a resource. By default the relationship is for child. The first level is always resources:

/rest/v1/resourceService/path/RESOURCE
While all additional paths are specified after the resource. For example:
/rest/v1/resourceService/path/RESOURCE/PROJECT/ENTITY

Parameter Description
relationship optional Return all attributes that have that type of relationships with the base entity. The default is CHILD.
/rest/v1/resourceService/find

This call is used to find paths, and entities that match a specific term, or ontology information.

Parameter Description
term optional Search for all paths containing the string
ontologyType optional Search for all paths that have an ontology type of this, with a given term. Must be used with ontologyTerm
ontologyTerm optional Search for all paths that have an ontology term of this given the ontologyType. Must be used with ontologyType.
Query

As described above the IRCT is a resource driven API. For querying this means that each resource defines what components of a query that it supports and what they can do. Queries are defined inside the IRCT of containing clauses. These clauses can be of three types; Select, Where, and Join. Select clauses instruct the resource to return these data types, while Join clauses tell the resource how to join the data. Where clauses are more complicated as they tell the resource how to filter the data using different predicates. Predicates are a set of different filtering operations that can be performed by a query on a field. This may be something simple as filtering out all entries that a null value, or as complicated as returning only the genomic rarity of a SNP. Not all resources will support all three different types of clauses.

/rest/v1/queryService/startQuery

Starts a query and returns a conversation id that needs to be passed if the query is being created by adding components.

/rest/v1/queryService/saveQuery

Saves the query so that it can be run later. It requens a query id that can be used to retrieve the query.

/rest/v1/queryService/loadQuery

Loads the saved query, and returns a conversation id that can then be used to run the query.

Parameter Description
queryId required Query Identifier
/rest/v1/queryService/clause

A post call that adds a Select, where or Join clause to a query.

Body
A JSON object representing the query and returns a clause id.

/rest/v1/queryService/clause?type=where

A call that adds a where clause to a query and returns a clause id.

Parameter Description
cid required Query Identifier
path required Path the clause is running against
predicate required Type of predicate that is going to be run
logicalOperator optional Type of logical operator to use
clauseId optional Replaces a given clause
data-* optional A series of fields for the where clause
/rest/v1/queryService/clause?type=select

A call that adds a select clause to a query and returns a clause id. Multiple selects can be combined into one column by setting the alias to the same value.

Parameter Description
cid required Query Identifier
clauseId optional Replaces a given clause
path required Path the clause is running against
alias required Alias of the clause.
/rest/v1/queryService/clause?type=join

A call that adds a join clause to a query and returns a clause id.

Parameter Description
cid required Query Identifier
clauseId optional Replaces a given clause
path required Path the clause is running against
joinType required Type of join to run
field-* optional A series of fields for the where clause
/rest/v1/queryService/runQuery

Runs the query

Parameter Description
cid required Query Identifier
/rest/v1/queryService/runQuery

A post call that runs a query based on a JSON representation passed in the body.

Body
A JSON object representing the query and returns a clause id.

Process

In a manner similar to query creation and execution, processes can be created to run a method on a remote resource if the resource already implements it . All processes take in a series of fields as one input, but unlike queries do not have a concept similar to clauses. Processes can be defined to take results of queries, or other processes as inputs. This allows for an entire several actions to be chained together to create a desired process.

/rest/v1/processService/startProcess

Starts a process and returns a conversation id that needs to be passed if the process is being created by adding components.

/rest/v1/processService/process

A call that sets the parameters for running a process

Parameter Description
cid required Process Identifier
resource required Resource Identifier
processName required Name of the process
data-* optional A series of data fields for the process
/rest/v1/processService/runProcess

Runs the process

Parameter Description
cid required Process Identifier
Result

Since the IRCT interacts with different resources it needs to be able to securely store, and make accessible the results of its different actions (Query, Process). Results can be of several different types (TABULAR, JSON, HTML, IMAGE). Depending on the result type they can be downloaded in different formats (e.g. XML, CSV, Excel). Results are only available to the person who ran the action that created them. However future releases will allow for different results to be more easily shared with a group or be made public.

/rest/v1/resultService/available

Returns an array of available results

/rest/v1/resultService/resultStatus/$RESULTID

Returns the status of the result

Parameter Description
$RESULTID required Result Identifier
/rest/v1/resultService/availableFormats/$RESULTID

Returns an array of formats that the result can be returned in

Parameter Description
$RESULTID required Result Identifier
/rest/v1/resultService/result/$RESULTID/$FORMAT

Returns an array of formats that the result can be returned in

Parameter Description
$RESULTID required Result Identifier
$FORMAT required Format of the file
download optional Value must be set to Yes, or No. When set to Yes the content-disposition of the response header is set as an attachment with the file name IRCT-RESULTID.FORMAT