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.
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.
This call returns a randomly generated number that is used to ensure a secure connection
This call creates an IRCT key for secure access outside of a browser
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 |
This call is used to create a secure session outside of a browser
Parameter | Description |
---|---|
KEY required | IRCT access key |
Ends a secure session
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.
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 |
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/RESOURCEWhile 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. |
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. |
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.
Starts a query and returns a conversation id that needs to be passed if the query is being created by adding components.
Saves the query so that it can be run later. It requens a query id that can be used to retrieve the query.
Loads the saved query, and returns a conversation id that can then be used to run the query.
Parameter | Description |
---|---|
queryId required | Query Identifier |
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.
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 |
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. |
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 |
Runs the query
Parameter | Description |
---|---|
cid required | Query Identifier |
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.
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.
Starts a process and returns a conversation id that needs to be passed if the process is being created by adding components.
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 |
Runs the process
Parameter | Description |
---|---|
cid required | Process Identifier |
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.
Returns an array of available results
Returns the status of the result
Parameter | Description |
---|---|
$RESULTID required | Result Identifier |
Returns an array of formats that the result can be returned in
Parameter | Description |
---|---|
$RESULTID required | Result Identifier |
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 |