Skip to content
Olivier Gueudelot edited this page Aug 22, 2016 · 3 revisions

Resources

Business resources

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" }]
	}]
	

}

Technical resources

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>)"
}

API Description

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
	# 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.

special URL

	# 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"
	}


users

	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

projects

	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

analyses

	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

templates

selections

subjects

samples

variants

jobs

	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

logs

search

Clone this wiki locally