Skip to content

Rest API

Jump to bottom
Johan Viklund edited this page Sep 28, 2017 · 32 revisions

Documentation of the REST API.

Table of contents

Overview

/api/users/me
Information about the current user
/api/countries
A list of all countries on the planet.
/api/datasets
List datasets with information about them (should paginate by default)
/api/datasets/<dataset>
Information on one dataset.
/api/datasets/<dataset>/logo
The dataset logo (an image)
/api/datasets/<dataset>/files
Downloadable files for the current dataset
/api/datasets/<dataset>/create_linkhash
Create linkhash
/api/datasets/<dataset>/sample_set
Information about the underlying sample set and study
/api/datasets/<dataset>/users
Protected. List users for dataset
/api/datasets/<dataset>/users/<users>/request
Request access
/api/datasets/<dataset>/users/<users>/approve
Protected. Approve user
/api/datasets/<dataset>/users/<users>/revoke
Protected. Revoke user
/api/datasets/<dataset>/versions
List available versions
/api/datasets/<dataset>/versions/<version>
Information about a specific version.
/api/beacon/info
Information about the beacon
/api/beacon/query
Query the beacon

/api/users/me

{
    user: "...",
    email: "..."
}

/api/countries

[
    'Angola',
    'Azerbadjan',
    ...
]

/api/datasets

A list of json objects (filtered on server so unavilable datasets are not shown):

This is the source for the content on the main landing page.

[
    {
        short_name: "...",
        full_name: "...",
        browser_uri: "...",
        beacon_uri: "...",
        avg_seq_depth: 0.0,
        seq_type: "...",
        seq_tech: "...",
        seq_center: "...",
        dataset_size: 0,

        version: {
            version: "...",
            description: "...",
            terms: "...",
            var_call_ref: "...",
            available_from: "2017-08-23T12:00:00",
        },

        has_image: False,

        is_admin: False,
        has_access: False,
        has_requested_access: False,
    },
    ...
]

This is a big join over the dataset, dataset_current_version, dataset_access, user and dataset_logo tables. It's possible to also include study information on the main page, but then we're joining 2 more tables.

/api/datasets/<dataset>

Current version only

{
    short_name: "...",
    full_name: "...",
    browser_uri: "...",
    beacon_uri: "...",
    avg_seq_depth: 0.0,
    seq_type: "...",
    seq_tech: "...",
    seq_center: "...",
    dataset_size: 0,

    version: {
        version: "...",
        available_from: "2017-08-23T12:00:00",
        description: "...",
        terms: "...",
        var_call_ref: "...",
    },

    has_image: False,

    is_admin: False,
    has_access: False,
    has_requested_access: False,
}

/api/datasets/<dataset>/logo

Returns a binary stream representing the logo in the format of the Content-Type.

/api/datasets/<dataset>/sample_set

{
    sample_set: {
        ethnicity: "...",
        collection: "...",
        sample_size: 0,
    },

    study: {
        pi_name: "...",
        pi_email: "...",
        contact_name: "...",
        contact_email: "...",
        title: "...",
        description: "...",
        ts: "2017-08-23T12:00:00",
        doi: "...",
    }
}

/api/datasets/<dataset>/files

{
    files: [
        {
           name: "...",
           uri: "...",
           hashes: [
               {
                   hash: "...",
                   uri: "..."
               }
           ]
        },
        ...
    ],
}

/api/datasets/<dataset>/create_linkhash

POST

{
    hash: "...",
    uri: "...",
    file: {
           name: "...",
           uri: "..."
    },
}

/api/datasets/<dataset>/users

[
    {
        name: "...",
        email: "...",
        affiliation: "...",
        country: "...",
        has_access: False,
        is_admin: False,
        wants_newsletter: False
    },
    ...
]

/api/datasets/<dataset>/users/<user>/request

POST with the following:

{
    userName: "...",
    email: "...",
    affiliation: "...",
    country: "...",
    newsletter: "..."
}

Return value is either a 200 or a 400 HTTP status depending on success/failure of the action.

/api/datasets/<dataset>/users/<user>/approve

POST

{
    email: "...",
    dataset: "...",
}

/api/datasets/<dataset>/users/<user>/revoke

POST

{
    email: "...",
    dataset: "...",
}

/api/datasets/<dataset>/versions

[
    {
        name: "...",
        available_from: "2017-08-23",
    },
]

/api/datasets/<dataset>/versions/<version>

This should be the same information as for the /api/datasets/<dataset> endpoint but from the perspective of the requested version.

/api/beacon/info

{
    id: "...",
    name: "...",
    organisation: "...",
    api: "...",
    datasets: [
        id: "...",
        reference: "...",
    ],
    homepage: "...",
    queries: [
        "...",
        ...
    ]
}

/api/beacon/query

Request has the get parameters:

chrom: "...",
pos: 0,
dataset: "...",
referenceAllele: "...",
allele: "...",
refernce: "..."

Response JSON:

{
    response: {
        exists: False,
        observed: 0,
        externalUrl: "..."
    },
    query: {
        chromosome: "...",
        position: 0,
        referenceAllele: "...",
        allele: "...",
        dataset: "...",
        reference: "..."
    }
    beacon: "..."
}
Clone this wiki locally