REST API resources¶
API root¶
The API root resource contains links to top-level resources in addition to a server status code.
The root resource representation has the following fields:
- uri (uri)
- URI for this resource.
- status (string)
- Currently always
ok
, but future versions of the API might add other values (e.g.maintanance
). - api_version (string)
- API version (see Versioning).
- authentication (object)
- Link to the authentication resource.
- genome (object)
- Link to the genome resource.
- annotation_collection (object)
- Link to the annotation collection resource.
- coverage_collection (object)
- Link to the coverage collection resource.
- data_source_collection (object)
- Link to the data_source collection resource.
- sample_collection (object)
- Link to the sample collection resource.
- token_collection (object)
- Link to the token collection resource.
- user_collection (object)
- Link to the user collection resource.
- variant_collection (object)
- Link to the variant collection resource.
- variation_collection (object)
- Link to the variation collection resource.
-
GET
/
¶ Returns the resource representation in the root field.
Example request:
GET / HTTP/1.1
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "root": { "uri": "/", "api_version": "0.3.0", "status": "ok", "authentication": { "uri": "/authentication" }, "genome": { "uri": "/genome" }, "annotation_collection": { "uri": "/annotations/" }, "coverage_collection": { "uri": "/coverages/" }, "data_source_collection": { "uri": "/data_sources/" }, "sample_collection": { "uri": "/samples/" }, "token_collection": { "uri": "/tokens/" }, "user_collection": { "uri": "/users/" }, "variant_collection": { "uri": "/variants/" }, "variation_collection": { "uri": "/variations/" } } }
Authentication¶
This resource reflects the current authentication state.
The authentication resource representation has the following fields:
- uri (uri)
- URI for this resource.
- authenticated (boolean)
- Whether or not the request is authenticated.
- user (object)
- Link to a user resource if the request is authenticated, null otherwise.
-
GET
/
¶ Returns the resource representation in the authentication field.
Example request:
GET /authentication HTTP/1.1
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "authentication": { "uri": "/authentication", "authenticated": true, "user": { "uri": "/users/1" "added": "2012-11-30T20:14:27.954255", "email": null, "login": "admin", "name": "Admin User", "roles": [ "admin" ], } } }
Genome¶
If the server is configured with a reference genome, this resource lists its chromosomes.
The genome resource representation has the following fields:
- uri (uri)
- URI for this resource.
- chromosomes (list of string)
- List of chromosome names.
-
GET
/
¶ Returns the resource representation in the genome field.
Annotations¶
Annotation resources model sets of variants annotated with observation frequencies.
An annotation resource is a tasked resource. The associated server task is calculating frequencies on the linked original data source and writing the annotated data to the linked annotated data source.
An annotation is represented as an object with the following fields:
- uri (uri)
- URI for this resource.
- task (object)
- Task information, see Tasked resources.
- original_data_source (object)
- Link to a data source resource (embeddable).
- annotated_data_source (object)
- Link to a data source resource (embeddable).
Todo
Include and document the associated queries.
Collection¶
See also
-
GET
/annotations/
¶ Returns a collection of annotations in the annotation_collection field.
Note
Requires having the admin role or being the user specified by the user filter.
Available filters:
- user (uri)
-
POST
/annotations/
¶ Adds an annotation resource.
Note
Requires having the admin role or being the owner of the data source specified by the data_source field.
Queries may have additional requirements depending on their expression:
- Query expressions of the form
sample:<uri>
require one of the following:- Having the admin role.
- Owning the sample specified by
<uri>
. - The sample specified by
<uri>
being public.
- Query expressions of the form
*
require having the admin, annotator, or trader role, where the trader role additionally requires that data_source has been imported as variation in an active sample. - Query expressions containing only group clauses require the same
as those of the form
*
, where the annotator and trader roles additionally require having the group-querier role. - Other query expressions require the same as those containing only group clauses, where the annotator and trader roles require having the querier role instead of the group-querier role.
Required request data:
- data_source (uri)
Accepted request data:
- name (string)
- queries (list of object)
Every object in the queries list defines a query; a set of samples over which observation frequencies are annotated. When annotating a VCF data source, any samples having this data source as variation are excluded.
- Query expressions of the form
Instances¶
-
GET
/annotations/<id>
¶ Returns the annotation representation in the annotation field.
Note
Requires having the admin role or being the owner of the annotation.
-
PATCH
/annotations/<id>
¶ Updates an annotation resource.
Note
Requires having the admin role.
Accepted request data:
- task (object)
Coverages¶
Coverage resources model sets of genomic regions having high enough coverage in sequencing to do variant calling.
A coverage resource is a tasked resource. The associated server task is importing the coverage data from the linked data source in the server database.
A coverage is represented as an object with the following fields:
- uri (uri)
- URI for this resource.
- task (object)
- Task information, see Tasked resources.
- data_source (object)
- Link to a data source resource (embeddable).
- sample (object)
- Link to a sample resource (embeddable).
Collection¶
See also
-
GET
/coverages/
¶ Returns a collection of coverages in the coverage_collection field.
Note
Requires one or more of the following:
- Having the admin role.
- Being the owner of the sample specified by the sample filter.
- Setting the sample filter to a public sample.
Available filters:
- sample (uri)
-
POST
/coverages/
¶ Adds a coverage resource.
Note
Requires having the admin role or being the owner of the sample specified by the sample field.
Required request data:
- data_source (uri)
- sample (uri)
Data sources¶
Data source resources model data from files that are either uploaded to the server by the user or generated on the server.
The actual data is modeled by the blob subresource type.
A data source is represented as an object with the following fields:
- uri (uri)
- URI for this resource.
- added (string)
- Date and time this data source was added, see Date and time.
- gzipped (boolean)
- Whether or not the data is compressed using gzip.
- name (string)
- Human readable data source name.
- filetype (string)
- Data filetype. Possible values for this field are bed, vcf, and csv.
- data (object)
- Link to a blob resource.
- user (object)
- Link to a user resource (embeddable).
Collection¶
See also
-
GET
/data_sources/
¶ Returns a collection of data sources in the data_source_collection field.
Note
Requires having the admin role or being the user specified by the user filter.
Available filters:
- user (uri)
Orderable by: name, filetype, added
-
POST
/data_sources/
¶ Adds a data source resource.
Note
Requires user authentication.
Required request data:
- name (string)
- filetype (string)
Accepted request data:
- gzipped (boolean)
- local_file (string)
- data (file)
Instances¶
-
GET
/data_sources/<id>
¶ Returns the data source representation in the data_source field.
Note
Requires having the admin role or being the owner of the data source.
-
PATCH
/data_sources/<id>
¶ Updates a data source resource.
Note
Requires having the admin role or being the owner of the data source.
Accepted request data:
- name (string)
Groups¶
Group resources model sample groups (e.g., disease type).
A group is representend as an object with the following fields:
- uri (uri)
- URI for this resource.
- name (string)
- Human readable group name.
Samples¶
Sample resources model biological samples which can contain one or more individuals.
A sample is represented as an object with the following fields:
- uri (uri)
- URI for this resource.
- active (boolean)
- Whether or not this sample is active.
- added (string)
- Date and time this sample was added, see Date and time.
- coverage_profile (boolean)
- Whether or not this sample has a coverage profile.
- name (string)
- Human readable sample name.
- notes (string)
- Human readable notes in Markdown format.
- pool_size (integer)
- Number of individuals in this sample.
- public (boolean)
- Whether or not this sample is public.
- user (object)
- Link to a user resource (embeddable).
- groups (list of object)
- Links to group resources (embeddable).
Collection¶
See also
-
GET
/samples/
¶ Returns a collection of samples in the sample_collection field.
Note
Requires one or more of the following:
- Having the admin role.
- Being the user specified by the user filter.
- Setting the public filter to True.
Available filters:
- groups (uri)
- public (boolean)
- user (uri)
Orderable by: name, pool_size, public, active, added
-
POST
/samples/
¶ Adds a sample resource.
Note
Requires having the admin or importer role.
Required request data:
- name (string)
Accepted request data:
- coverage_profile (boolean)
- groups (list of uri)
- notes (string)
- pool_size (integer)
- public (boolean)
Instances¶
-
GET
/samples/<id>
¶ Returns the sample representation in the sample field.
Note
Requires one or more of the following:
- Having the admin role.
- Being the owner of the sample.
- The sample is public.
-
PATCH
/samples/<id>
¶ Updates a sample resource.
Note
Requires having the admin role or being the owner of the sample.
Accepted request data:
- active (boolean)
- coverage_profile (boolean)
- groups (list of uri)
- name (string)
- notes (string)
- pool_size (integer)
- public (boolean)
Tokens¶
Token resources model authentication tokens for API users.
A token is represented as an object with the following fields:
- uri (uri)
- URI for this resource.
- added (string)
- Date and time this sample was added, see Date and time.
- key (string)
- Token key used for authentication.
- name (string)
- Human readable sample name.
- user (object)
- Link to a user resource (embeddable).
Collection¶
See also
-
GET
/tokens/
¶ Returns a collection of tokens in the collection field.
Note
Requires having the admin role or being the user specified by the user filter.
Note
This request is only allowed using HTTP Basic Authentication, not token authentication.
Available filters:
- user (uri)
Orderable by: name, added
-
POST
/tokens/
¶ Adds a token resource.
Note
Requires having the admin or being the user specified by the user data field.
Note
This request is only allowed using HTTP Basic Authentication, not token authentication.
Required request data:
- user (uri)
- name (string)
Instances¶
-
GET
/tokens/<id>
¶ Returns the token representation in the token field.
Note
Requires having the admin role or being the owner of the token.
Note
This request is only allowed using HTTP Basic Authentication, not token authentication.
-
PATCH
/tokens/<id>
¶ Updates a token resource.
Note
Requires having the admin role or being the owner of the token.
Note
This request is only allowed using HTTP Basic Authentication, not token authentication.
Accepted request data:
- name (string)
Users¶
User resources model API users and their permissions.
A user is represented as an object with the following fields:
- uri (uri)
- URI for this resource.
- added (string)
- Date and time this user was added, see Date and time.
- email (string)
- User e-mail address.
- login (string)
- Login name used for authentication.
- name (string)
- Human readable user name.
- roles (list of string)
- Roles for this user. Possible values for this field are admin, importer, annotator, and trader.
Collection¶
See also
-
GET
/users/
¶ Returns a collection of users in the user_collection field.
Note
Requires having the admin role.
Orderable by: name, added
-
POST
/users/
¶ Adds a user resource.
Note
Requires having the admin role.
Note
This request is only allowed using HTTP Basic Authentication, not token authentication.
Required request data:
- login (string)
- password (string)
Accepted request data:
- name (string)
- email (string)
- roles (list of string)
Instances¶
-
GET
/users/<id>
¶ Returns the user representation in the user field.
Note
Requires having the admin role or being the requested user.
-
PATCH
/users/<id>
¶ Updates a user resource.
Note
Requires having the admin role or being the requested user.
Note
This request is only allowed using HTTP Basic Authentication, not token authentication.
Accepted request data:
- email (string)
- login (string)
- name (string)
- roles (list of string)
Variants¶
Variant resources model genomic variants with their observed frequencies.
Note
The implementation of this resource is still in flux and it is therefore not documented.
A variant is represented as an object with the following fields:
- uri (uri)
- URI for this resource.
Variations¶
Variation resources model sets of variant observations.
A variation resource is a tasked resource. The associated server task is importing the variation data from the linked data source in the server database.
A variation is represented as an object with the following fields:
- uri (uri)
- URI for this resource.
- task (object)
- Task information, see Tasked resources.
- data_source (object)
- Link to a data source resource (embeddable).
- sample (object)
- Link to a sample resource (embeddable).
Collection¶
See also
-
GET
/variations/
¶ Returns a collection of variations in the variation_collection field.
Note
Requires one or more of the following:
- Having the admin role.
- Being the owner of the sample specified by the sample filter.
- Setting the sample filter to a public sample.
Available filters:
- sample (uri)
-
POST
/variations/
¶ Adds a variation resource.
Note
Requires having the admin role or being the owner of the sample specified by the sample field.
Required request data:
- data_source (uri)
- sample (uri)