WS [ ]

Welcome to Regovar 0.12.0

This page is for developpers who want to know how to use Regovar via the Rest api.

Choose in the top menu bar the "main" section of the API you want to see. The last one "Realtime" is a special tab where all realtime notification are logged. In addition, the color of the indicates if the realtime is active or not :

  • : no websocket connection available;
  • : error occured;
  • : websocket active (no problem detected).

Endpoints of the API have an icon:

  • : The endpoint is ok. No know problem with it;
  • : Working but some limitation;
  • : Not working. Know bug with this endpoint.

Sometime, git issue are link in the description of the endpoint when there issue, bug or feature implementation planned. Be free to have a look to github issue. All help is welcome \o/ !

Miscellaneous

Access
No authentication required.
Description
GET /config
Return the server configuration of Regovar.
Test
Access
No authentication required.
Description
GET /api
Return this webpage. Documentation and dynamic examples about the Regovar API.
Test
Access
Authentication required.
Description
GET /welcome
Return the server "welcome" data for Regovar client : All data to init the client.
Test

Result

                

File REST api

This api allow you to manage file operation on the server : list all existings file, uploading a new one, etc.

Access
Authentication required.
Description
GET /files
Retrieve the list of all file stored on Regovar server.
Test
-
Access
Authentication required.
Description
GET /file/{file_id}
Retrieve all information about the file.
Parameters
file_id
The Regovar id of the file.
Test
Access
Authentication required.
Access
Authentication required.
Warning ! Implemenation of this endpoint is not finished.
Description
PUT /file/{file_id}
Update Regovar metada of the file with provided json data.
Parameters
file_id
The Regovar id of the file.
Body
{key : value}
Information to update in the file. Note that only following fields are allowed to be edited via the Rest api : "name", "type", "tags".
Test
Query :
Body :

Access
Authentication required.
Description
DELETE /file/{file_id}
Delete the file. The file is deleted in the Regovar database (SQL) and in the Regovar filesystem. If the file was referenced by one or several jobs, they still refer to this file_id, but of course nobody will be able to retrieve which file correspond to this id.
Parameters
file_id
The Regovar id of the file.
Test
Access
Authentication required.
Info : Checksum TUS extension is planned to be implemented/supported. But not yet available.
Description
Regovar implement the TUS protocol for uploading file on the server. Please, refer to the official documentation for more details.
POST /file/upload
Create a new "empty" file on Regovar server that will be used to handle data and progress regarding the upload. This query will return the id of the file to use to upload the file.

OPTIONS /file/upload
To know how TUS is configured on the server.

HEAD /file/upload/{file_id}
To retrieve the offset where the upload of the file shall be resume.

PATCH /file/upload/{file_id}
To upload a chunk a of file.

DELETE /file/upload/{file_id}
To delete the uploading file.
Parameters
file_id
The Regovar id of the file.
Test

Result

                

Pipeline REST api

Access
Authentication required.
Description
GET /pipelines
Retrieve the list of all pipelines stored on Regovar server.
Test
-
Access
Authentication required.
Description
GET /pipeline/{pipe_id}
Retrieve all information about the pipeline.
Parameters
pipe_id
The Regovar id of the pipeline.
Test
Access
Authentication as Administrator required.
Description
GET /pipeline/install/{file_id}
Install a pipeline from the image file which have been already uploaded on the server and have the id {file_id}.
Parameters
file_id
The Regovar id of the file. This file will be used as pipeline image by the Regovar container manager.
Test
Access
Authentication as Administrator required.
Description
DELETE /pipeline/{pipe_id}
Delete the pipeline. The pipeline is deleted in the Regovar database (SQL) and in the Regovar filesystem. All jobs of this pipe are still here, and they still refer to this pipeline_id, but of course nobody will be able to retrieve which pipeline correspond to this id.
Parameters
pipe_id
The Regovar id of the pipeline.
Test

Result

                

Job REST api

Access
Authentication required.
Description
GET /job?...
Retrieve the list of all job on Regovar server.
Test
-
Access
Authentication required.
Description
GET /job/{job_id}
Retrieve all information about the job.
Parameters
job_id
The Regovar id of the job.
Test
Access
Authentication required.
Description
POST /job
Create a new job with provided json configuration in the body of the post request.
ContentType
'application/json'
Body
As a json request, the body is a json dictionnary with following keys:
"pipeline_id" : int
Refer to the id of a pipeline "ready" to be used on the Regovar server.

"name" : str
The name of the job.

"config" : {json}
The json data that will be provided to the pipeline to configure the job. You can download the json form use to generate this config by looking the form.json document of the pipe (/pipeline/{pipeline_id}). If the pipeline do no provide form.json file, then, you can let this entry empty.
IMPORTANT : the form.json describe the form to set the config json. so you dont have to set config with all information describe in the form.json file. The config shall be a simple key-value dictionnary


"inputs" : [int,...]
A list of Regovar file's file id. Note that if one or several file are not ready to be used (still uploading by example), je job will be in "waiting" status and will automaticaly start when all inputs files will be ready. Of course, if a file is deleted or its upload never end, the job will never start. And you will have to stop or delete it yourself.
Test
Main query :
Body : to set config, retrieve the form.json document of the pipeline you want to run (/pipeline/{pipeline_id})

Access
Authentication required.
Description
GET /job/{job_id}/pause
Pause the execution of the job (if this feature is supported by the pipeline).
Parameters
job_id
The Regovar id of the job.
Test
Access
Authentication required.
Description
GET /job/{job_id}/start
Restart a job which have been paused.
Parameters
job_id
The Regovar id of the job.
Test
Access
Authentication required.
Description
GET /job/{job_id}/cancel
Stop the execution of the job. Then the job status is "canceled" and cannot be start again (a new job shall be created).
Parameters
job_id
The Regovar id of the job.
Test
Access
Authentication as Administrator required.
Description
GET /job/{job_id}/finalize
This action is done automaticaly by Regovar when the execution of the job is done. But if for some raison, the pipeline is not able to indicate to Regovar that its task is finished, Regovar cannot finalize the job and doing technical tasks like stopping and deleting the virtual machine used for the job. So for these pipelines, the api provide a way to manualy finalize a job.
Parameters
job_id
The Regovar id of the job.
Test
Access
Authentication required.
Description
GET /job/{job_id}/monitoring
Return job's informations with additional monitoring informations: technical ressources usage (RAM, CPU, ...) and execution's log (only last 100 lines).
Parameters
job_id
The Regovar id of the job.
Test

Result

                            

Jobs status

Databases REST api

Access
Authentication required.
Description
GET /db
Return the list of database's reference available on Regovar server.
Test
Access
Authentication required.
Description
GET /db/{ref_name}
Return the list of databases for the provided reference.
Parameters
ref_name
The name of the reference.
Test

Result

                    

Annotations REST api

API to manage annotation's databases and fields used for dynamic filtering of variants.

Access
Authentication required.
Description
GET /annotation
Return the list of database's reference available on the Regovar variants database.
Test
Access
Authentication required.
Description
GET /annotation/{ref_name}
Return the list of annotations databases for the provided reference.
Parameters
ref_id
The id of the reference.
Test
Access
Authentication required.
Description
GET /annotation/db/{db_id}
Return many details on the annotations database and the list of all available annotation's fields available.
Parameters
db_id
The id of the annotation database.
Test
Access
Authentication required.
Description
GET /annotation/field/{field_id}
Return all informations about the annotations field.
Parameters
field_id
The id of the annotation field.
Test
Access
Authentication as Administrator required.
Description
DELETE /annotation/db/{db_id}
Delete an annotation database with all its fields. The user have to take care regarding side effects of this actions on his analysis.
Parameters
ref_id
The id of the database.
Test

Result

                    

Sample REST api

Access
Authentication required.
Description
GET /samples
Return the list of samples in the database.
Test
Access
Authentication required.
Description
GET /samples/ref/{ref_id}
Return the list of samples for the provided reference id in the database.
Test
Access
Authentication required.
Description
GET /sample/{sample_id}
Get all details about the sample.
Parameters
sample_id
The id of the sample.
Test
Access
Authentication required.
Description
GET /sample/import/{file_id}/{ref_id}?...
Import samples data from file. Today, only VCF(.gz) files are supported.
Optional query parameters allow you to link the samples imported to a subject and or an analysis.
Parameters
file_id
The id of the file to import.

ref_id
The id of the reference to use.
Test

Result

                    

Analysis REST api

Access
Authentication required.
Description
GET /analyses
Return the list of all analyses.
Test
Access
Authentication required.
Description
GET /analysis/{analysis_id}
Return the details of the analysis.
Parameters
analysis_id
The id of the analysis.
Test
Access
Authentication required.
Description
POST /analysis
Create a new analysis with provided information. The template_id is optional.
Body
{
    "project_id":int,
    "name":str, 
    "reference_id":int, 
    "template_id":int
}

The only mandatory fields are project_id and name. If the reference_id is not set, the default (hg19) is taken. template_id allow you to initialize the analysis with predefined filter, attributes and fields.
Test
Query :
Body :

Access
Authentication required.
Description
PUT /analysis/{analysis_id}
Update information about the analysis. Data that can be updated with this method are :
  • name : the name of the analysis
  • owner_id : the user that own this analysis
  • project_id : the project that own this analysis
  • filter : the current filter (read the doc about building filter)
  • fields : the list of fields to display in the grid
  • selection : the list of selected variants/transcripts
  • comment : a free comment about the analysis
  • samples : the list of tuple (samples'ids, optional nickname) used for this analysis
  • attributes : the list of attributes and their values for each sample
  • filters : the list of saved filters
Body
{
    "name":str, 
    "owner_id":int,
    "project_id":int,
    "filter":dict,
    "fields":[int],
    "selection":[int],
    "comment":str,
    "samples":[(int,str)],
    "attributes":[{"name":str, "samples_values":[{ : }]}],
    "filters":[{"name":str, "filter":dict}]
}

Test
Main query :

Access
Authentication required.
Description
GET /analysis/{analysis_id}/load/{file_id}
Load a file into the analysis. Supported file are :
  • VCF / GVCF : import samples, variants and annotations in the database add sample to this analysis;
  • PED / FAM : define attributes to manage pedigree. If sample's name used in the ped file doesn't match with sample's name or nickname used in the analysis, the attribute will be created, but no value will be set for corresponding sample.

  • Note : The file must be already uploaded.
Parameters
analysis_id
The id of the analysis.

file_id
The id of the file to load.
Test
Access
Authentication required.
Description
GET /analysis/{analysis_id}/filter
Return the list of filters saved for this analysis.
Parameters
analysis_id
The id of the analysis.
Test
Access
Authentication required.
Description
POST /analysis/{analysis_id}/filter
Create a new analysis with provided information. The template_id is optional.
Parameters
analysis_id
The id of the analysis.
Body
{
    "name":str, 
    "filter":json, 
    "description":str
}

The only mandatory fields are name and filter.
Read the doc about the json format used to describe filter : TODO.
Test
Query :
Body :

Access
Authentication required.
Description
DELETE /analysis/{analysis_id}/filter/{filter_id}"
Delete the filter.
Parameters
analysis_id
The id of the analysis.
Test
Access
Authentication required.
Description
POST /analysis/{analysis_id}/filtering
Apply the provided filter and return the list of filtered variants.
Parameters
analysis_id
The id of the analysis.
Body
{
    "filter": json, 
    "fields": [], 
    "order": [],
    "limit": int,
    "offset": int
}

Read the doc about the json format used to describe filter : TODO.
Test
Query :
Body :

Access
Authentication required.
Description
POST /analysis/{analysis_id}/filtering/count
Apply the provided filter and return the total count of results that match the filter.
Parameters
analysis_id
The id of the analysis.
Body
{
    "filter": json, 
    "fields": [], 
    "order": []
}

Read the doc about the json format used to describe filter : TODO.
Test
Query :
Body :

Access
Authentication as Administrator required.
Description
GET /analysis/{analysis_id}/clear_temps_data
Clear temporary data of the analysis (to save disk space by example)
Parameters
analysis_id
The id of the analysis.
Test

Result

                    

Sample REST api

Access
No authentication required.
Description
GET /users
Return the list of all user in the database.
Test
Access
Authentication required.
Description
GET /user/{user_id}
Get all details about the user.
Parameters
user_id
The id of the user.
Test
Access
Authentication as Administrator required.
Description
POST /user
Create a new user with provided information.
Body
{
    "login":str, 
    "firstname":str, 
    "lastname":str, 
    "email":str,
    "function":str,
    "location":str
    "password":str
}

Test
Query :
Body :

Access
Authentication required.
Description
PUT /user/{user_id}
Update the user with provided information.
Parameters
user_id
The id of the user.
Body
{
    "login":str, 
    "firstname":str, 
    "lastname":str, 
    "email":str,
    "function":str,
    "location":str
    "password":str
}

Test
Query :
Body :

Access
Authentication as Administrator required.
Description
DELETE /user/{user_id}
Delete the user.
Parameters
user_id
The id of the user.
Test
Access
No authentication required.
Description
POST /user/login
Attempt to log in with provided credentials.
Body
{
    "login":str,
    "password":str
}

Test
Query :
Body :

Access
Authentication required.
Description
GET /user/logout
Disconnect the user.
Test

Result

                    

Project REST api

Access
Authentication required.
Description
GET /projects
Return the list of all projects in the database.
Test
Access
Authentication required.
Description
GET /project/{project_id}
Get all details about the project.
Parameters
project_id
The id of the project.
Test
Access
Authentication required.
Description
POST /project
Create a new project with provided information.
Body
{
    "name":str, 
    "is_folder":bool, 
    "comment":str, 
    "parent_id":int
}

The only mandatory fields is name. By default is_folder is false. parent_id link to another project and allow to create arborescence of folder/project.
Test
Query :
Body :

Access
Authentication required.
Description
PUT /project/{project_id}
Update the project with provided information.
Parameters
project_id
The id of the project.
Body
{
    "name":str, 
    "is_folder":bool, 
    "comment":str, 
    "parent_id":int
}

Test
Query :
Body :

Access
Authentication required.
Description
DELETE /project/{project_id}
Deleting a project will automatically move all its analyses to the trash. The trash should be browse in an admin dedicated view. Technicaly, the trash is the special project with the id 0.
Parameters
project_id
The id of the project.
Test

Result

                    

Subject REST api

Access
Authentication required.
Description
GET /subjects
Return the list of all subject in the database.
Test
Access
Authentication required.
Description
GET /subject/{subject_id}
Get all details about the subject.
Parameters
subject_id
The id of the subject.
Test
Access
Authentication required.
Warning ! Implemenation of this endpoint is not finished.
Description
POST /subject
Create a new subject with provided information.
Body
{
    "date":datetime, 
    "message":str, 
    "type":enum, 
    "user_id":int,
    "project_id":int,
    "analysis_id":int,
    "file_id":int,
    "subject_id":int,
    "job_id":int,
    "pipeline_id":int
}

The only mandatory fields are date and message.
Test
Query :
Body :

Access
Authentication required.
Warning ! Implemenation of this endpoint is not finished.
Description
PUT /subject/{subject_id}
Update the subject with provided information.
Parameters
subject_id
The id of the subject.
Body
{
    "date":datetime, 
    "message":str, 
    "type":enum, 
    "user_id":int,
    "project_id":int,
    "analysis_id":int,
    "file_id":int,
    "subject_id":int,
    "job_id":int,
    "pipeline_id":int
}

Test
Query :
Body :

Result

                    

Panel REST api

Access
Authentication required.
Description
GET /panels
Return the list of all panel in the database.
Test
Access
Authentication required.
Description
GET /panel/{panel_id}
Get all details about the panel.
Parameters
panel_id
The id of the panel.
Test
Access
Authentication required.
Description
POST /panel
Create a new panel with provided information.
Body
{
    "name": str, 
    "description": str, 
    "owner": str,
    "shared": bool, 
    "version": str,
    "entries": json,
    "comment": str
}

The only mandatory fields are name and version.
Test
Query :
Body :

Access
Authentication required.
Description
PUT /panel/{panel_id}
Update the panel with provided information.
Parameters
panel_id
The id of the panel.
Body
{
    "name": str, 
    "description": str, 
    "owner": str,
    "shared": bool, 
    "version": str,
    "new_version": str,
    "entries": json,
    "comment": str
}

The only mandatory fields are name and version.
If you want to also update the name of the version, you have to put the former version name in the field version and put the new version name in the field new_version.
Test
Query :
Body :

Result

                    

Sample REST api

Access
Authentication required.
Description
GET /events
Return the list of 100 last event in the database.
Test
Access
Authentication required.
Description
POST /events
Get events list corresponding to provided filters
Body
{
    "event_id": int,
    "event_type": enum,
    "user_id": int, 
    "pipeline_id": int, 
    "job_id": int, 
    "project_id": int,
    "analysis_id": int,
    "subject_id": int,
    "file_id": int,
    "sample_id": int,
    "variant_id": json,
    "panel_id": str,
    "annotation_dbuid", str
}

All fields are optional.
Test
Query :
Body :

Access
Authentication required.
Description
GET /event/{event_id}
Get all details about the event.
Parameters
event_id
The id of the event.
Test
Access
Authentication required.
Description
POST /event
Create a new 'custom' event with provided information. Other event's types ('info', 'warning', 'error' and 'technical') cannot be created via the public api.
Body
{
    "date":datetime, 
    "message":str, 
    
    "event_id": int,
    "event_type": enum,
    "user_id": int, 
    "pipeline_id": int, 
    "job_id": int, 
    "project_id": int,
    "analysis_id": int,
    "subject_id": int,
    "file_id": int,
    "sample_id": int,
    "variant_id": json,
    "panel_id": str,
    "annotation_dbuid", str
}

The only mandatory field is message. Optional fields that end by "_id" are to link the event to an other objects in the database.
Test
Query :
Body :

Access
Authentication required.
Description
PUT /event/{event_id}
Update the event with provided information. Note that editing an event will also automatically create a 'technical' event that log that the event have been edited (which field and by which user).
Parameters
event_id
The id of the event.
Body
{
    "date":datetime, 
    "message":str, 
    "from_user_id":int,
    
    "event_id": int,
    "event_type": enum,
    "user_id": int, 
    "pipeline_id": int, 
    "job_id": int, 
    "project_id": int,
    "analysis_id": int,
    "subject_id": int,
    "file_id": int,
    "sample_id": int,
    "variant_id": json,
    "panel_id": str,
    "annotation_dbuid", str
}

Test
Query :
Body :

Access
Authentication required.
Description
DELETE /event/{event_id}
Delete the event with the provided id. Note that only 'custom' event can be deleted, and deleting an event will automatically create a 'technical' event that log the deletion of the event.
Test

Result

                    

Last message received

Historic

Date Sender Message Data
Apple Red These are red.
Date Sender Message Data