-
Notifications
You must be signed in to change notification settings - Fork 2
API
Olivier Gueudelot edited this page Aug 22, 2016
·
3 revisions
User
{
"id" : 1234
"email" : "user@regovar.org"
"firstname" : "Pierre"
"lastname" : "Dupont"
"function" : "Interne en génétique"
"location" : "CHU Angers"
"last_activity" : "2016-08-17"
"settings" : { "key" : "value" }
}
Project
{
"id" : 56
"name" : "X File"
"comments" : "Top secret project"
"parent_id" : NULL
"data" : { "key" : "value" }
}
Analysis
{
"id" : 23
"name" : "Analysis n°1"
"owner_id" : 1234
"project_id" : 56
"comments" : ""
"template_id" : 1
"template_settings" : ""
"creation_date" : "2016-08-01"
"update_date" : "2016-08-17"
"status" : "ready"
}
Template
{
"id" : 2
"name" : "HugoDims"
"author_id" : 1234
"description" : "Pipe for Hugo"
"version" : "V1.5"
"creation_date" : "2015-06-01"
"update_date" : "2016-04-12"
"parent_id" : 1
"status" : "validated"
"configuration" : ""
}
Selection
{
"id" : 56432
"analysis_id" : 23
"name" : "Child DeNovo"
"order" : 5
"comments" : "Selection of de novo variant of the child"
"query" : { filters : [{ "key" : "value"}] }
}
Subject
{
"id" : 897
"name" : "DEC PRO - 20160715"
"contact" : "Dr Toubib - CHU Paris"
"comments" : ""
"patient" :
{
"firstname" : "Proper"
"lastname" : "Declac"
"birthdate" : "1980-12-24"
"deathdate" : ""
"contact" : "Mr P. Declac - 0612345678"
}
"parents" : [896, 895]
"childs" : [899, 900, 902]
}
Sample
{
"id" : 654789
"name" : "Sample_785X6"
"comments" : "NGS Illumina HiSeqX - HP caller"
"subject_id" : 897
}
Variant
{
"id" : 123456789
"bin" : 156
"chr" : 2
"pos" : 54678231
"ref" : "A"
"alt" : ""
"annotations" : { }
samples : # Lazy loading : these fields are loaded only if in the request we ask to return variant of one or several sample(s)
[{
"sample_id" : 897
"genotype" : "h"
"deepth" : 51
"infos" : [{ "key" : "value" }]
}]
}
Job
{
"id" : 42689
"type" : "file_import"
"description" : "VCF import for Sample \"Sample_785X6\" (654789)"
"start" : "2016-08-17 16-28-47-1423"
"end" : ""
"progress" : 50.26
"user" : 1234
"priority" : "hight" # enum : low, normal, hight
}
Log
{
"job_id" : 42689
"date" : "2016-08-17 16-35-12-4735"
"type" : "warning"
"message" : "Variant normalization failled for the row 4587566"
# Note that the full log with potential exception trace and so on will be save
# on the server file system in the log file dedicated to this job
# path on the server : /{REGOVAR}/jobs/{job_id}/logs/
}
Searchresult
{
"keyword" : "Sample_785X6"
"resource_type" : "sample"
"resource_id" : 654789
"snippet" : "Sample_785X6 (DEC PRO - 20160715, <i>Dr Toubib - CHU Paris</i>)"
}
Here are the general principles followed by our API
-
Domaine : http://api.regovar.org/
-
Version : mandatory version number, a digit at the highest level of the uri path. The number represents a major API version for a given resource, which requires a change to the API works. http://api.regovar.org/1/
-
CRUD :
GET Read
POST Create / execute action
UPDATE Update
DELETE Delete
- API Response, error handling and HTTP code :
- The only HTTP code returned by the API will be :
- 200 : server goes fine
- 404 : request not found
- 403 : authentication required
- 5XX : server error
- The API response is always a JSON object using utf8 encoding
- JSON response always have the same attributes :
- success : boolean that indicates if the request was successful
- result : the result of the request
- error_code : in case of request error, this error_code provides information about the error. The possible error_code values are documented for each API
- msg : in cas of error, provides an English error message relative to the error
- The only HTTP code returned by the API will be :
# Successful response example
HTTP code : 200
{
success: true,
result:
{
logged_in: false,
challenge: "WpsbHdkBpRpHLMGQHZ1ri1uUqa4ce6Dw"
}
}
# Error response example
HTTP code : 200
{
msg: "Invalid request",
success: false,
error_code: "invalid_request"
}
-
Pagination : Pagination is managed via the URL query-string.
- Only one parameter : "?range={first}-{end}"
- Return result from {first} to {end} included (note that first element is 0)
- Default pagination is set in the parameter table of the database : see range_default and range_max parameters
- The reply always add following attribute in the successful API response :
- range_offset : the index of the first item returned by the query
- range_limit : the index of the last item returned by the query
- range_count : the total number of element that contains the collection
- range_max : the maximum number that can be a query, all at once.
HTTP code : 200
{
"success": true,
"result":
{
// Result of the request
}
"range_offset" : 0,
"range_limit" : 99,
"range_count" : 12452,
"range_max" : 1000,
}
-
Filter : It's possible to quickly filter result via the URL query-string.
- Limit the number of requested resources by specifying attributes and their corresponding expected values
- It is possible to filter a collection of several attributes simultaneously, and to allow more values for the same attribute filtered
- Directly use the name of the attribute equal to the expected values, each separated by a comma
- Only attribute of the resource can be filtered (no join between resource can be done by this way)
- Complex filtering (other operator than equal, regexp, join, ...) shall use the query action. See below of this page the section about API Actions
# Return list of users with lastname is equal to "Dupont"
https://api.regovar.org/1/user?lasname=Dupont
# Return 100 first "deletion's" variants of the sample 4865 on the chromosom 1, 2 and X
https://api.regovar.org/1/variant?sample_id=4865&chr=1,2,X&alt=&range=0-99
- Order :It's possible to sort result via the URL query-string.
- sort : contain attribute names, separated by commas, on which to perform the sort.
- desc : default sort is ascending to get so down (or descending), just add this parameter and specify which field that be sert descending (among fieds set with the sort attribute)
# Return list of users sort by lastname descending first then by firstname ascending
https://api.regovar.org/1/user?sort=lastname,firstname&desc=lastname
# Return list of users sort by firstname ascending first then by lastname ascending
https://api.regovar.org/1/user?sort=firstname,lastname
- Search : To be defined.
# Return the configuration of the server API
GET https://api.regovar.org/1/config
200
{
"domain" : "https://api.regovar.org/"
"version" : 1
"range_max" : 1000
"range_default" : 100
"db_uuid" : "256431-1451451-5412571581"
"db_version" : "V1.0.0"
"db_backup" : "2016-08-25"
"client_version" : "V1.0.0"
}
GET /users list of user (to use with filter and pagination attributes)
GET /users/{id} the user with the provided {id}
GET /users/me the connected user
POST /users create a new user
DELETE /users/{id} delete a user if possible (user shall not be linked to an analysis or a job)
PUT /users/{id} update an existing user
GET /projects list of projects
GET /projects/{id} the project with the provided {id}
GET /projects/{id}/analyses the analyses of the provided project
GET /projects/{id}/samples the samples of the provided project
GET /projects/{id}/subjects the subjects of the provided project
GET /projects/{id}/subjects the subjects of the provided project
POST /projects create a new project
DELETE /projects/{id} delete a project if possible (shall be empty)
PUT /projects/{id} update an existing project
GET /analyses list of analyses
GET /analyses/{id} the analyse with the provided {id}
POST /analyses create a new analyse
DELETE /analyses/{id} delete a analyse if possible (shall have no jobs in progress, will delete associated file/sample)
PUT /analyses/{id} update an existing project
GET /jobs list of jobs
GET /jobs/{id} the analyse with the provided {id}
POST /jobs create a new analyse
DELETE /jobs/{id} delete a analyse if possible (shall have no jobs in progress, will delete associated file/sample)
PUT /jobs/{id} update an existing project