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

Collection resources

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.

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

Collection resources

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)

Instances

GET /coverages/<id>

Returns the coverage representation in the coverage field.

Note

Requires having the admin role or being the owner of the coverage.

PATCH /coverages/<id>

Updates a coverage resource.

Note

Requires having the admin role.

Accepted request data:

  • task (object)

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

Collection resources

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)

Blobs

GET /data_sources/<id>/data

Returns the gzipped data source data.

Warning

The response body will not be a JSON document.

Note

Requires having the admin role or being the owner of the data source.

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.

Collection

See also

Collection resources

GET /groups/

Returns a colleciton of groups in the group_collection field.

POST /groups/

Adds a group resource.

Note

Requires having the admin or importer role.

Instances

GET /groups/<id>

Returns the group representation in the group field.

PATCH /groups/<id>

Updates a group resource.

Note

Requires having the admin role.

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

Collection resources

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

Collection resources

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

Collection resources

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.

Collection

See also

Collection resources

GET /variants/

Returns a collection of variants in the variant_collection field.

POST /variants/

Adds a variant resource.

Instances

GET /variants/<id>

Returns the variant representation in the variant field.

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

Collection resources

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)

Instances

GET /variations/<id>

Returns the variation representation in the variation field.

Note

Requires having the admin role or being the owner of the variation.

PATCH /variations/<id>

Updates a variation resource.

Note

Requires having the admin role.

Accepted request data:

  • task (object)