Skip to content

API Documentation

Jump to bottom
PJ Tatlow edited this page Nov 28, 2017 · 7 revisions

GET: /api/datasets

Response:

An object where the keys are dataset ids and the values are datasets Each dataset will have the values seen below in the example.

The description is in markdown format, with \n where a newline character would normally be. The uploadDate is a Unix timestamp in seconds representing when the dataset was created. The rest of the items should be pretty self-explanatory.

{
  "sampledataset": {
    "description": "This will be a description\n\n",
    "id": "sampledataset",
    "name": "Sample Dataset",
    "numFeatures": 20000,
    "numMetaTypes": 32,
    "numSamples": 250,
    "uploadDate": 1510576060,
    "featureDescription": "gene",
    "featureDescriptionPlural": "genes"
  }
}

GET: /api/datasets/:id/meta

Request:

:id - dataset id

Response:

An object with a meta key and a features key.

The meta key will be either:

  1. an object mapping metadata types (strings) to metadata values (objects)
  2. null meaning there are too many metadata types to search through in the browser. You can use the /api/datasets/:id/meta/search endpoint to search for metadata types

If meta is not null, each metadata value will have an key called options which will be either:

  1. An array of strings representing the available options, along with numOptions
  2. "continuous" meaning there are also min and max keys on the object
  3. null meaning there are again, too many options to search through on the browser. You can use the /api/datasets/:id/meta/:meta_type/search endpoint to search through the available options. numOptions will also be set.

The features key will always have numOptions and options, but options may be null, meaning you can search the available values using the /api/datasets/:id/features/search endpoint.

Example 1

{
  "meta": {
    "discreteVariable": {
      "numOptions": 3,
      "options": ["option1","option2","option3"]
    },
    "continuousVariable": {
      "min": 0,
      "max": 5,
      "options": "continuous"
    },
    "sampleID": {
      "numOptions": 1200,
      "options": null
    }
  },
  "features": {
    "numOptions": 190000,
    "options": null
  }
}

Example 2

{
  "meta": null,
  "features": {
    "numOptions": 3,
    "options": ["feature1","feature2","feature3"]
  }
}

GET: /api/datasets/:id/meta/:meta_type

Request:

:id - dataset id :meta_type - name of metadata type

Response:

An object representing the possible values for that metadata type. This is used when there are too many metadata types to search through, and you need to load the metadata values one by one. The values have the same possibilities as the response from this endpoint.

Example 1

{
  "numOptions": 3,
  "options": ["option1","option2","option3"]
}

Example 2

{
  "min": 0,
  "max": 5,
  "options": "continuous"
}

Example 3

{
  "numOptions": 1200,
  "options": null
}

GET: /api/datasets/:id/meta/search/:search_str

Request:

:id - dataset id :search_str - OPTIONAL search value to try and match

Response:

An array of strings, each one being a different metadata type that matched the search value. If no search value is provided, it will return the first 100 metadata types, as well as "sampleID". When a search value is provided, it will return a maximum of 100 values.

["metadata1","metadata12","sampleID"]

GET: /api/datasets/:id/meta/:meta_type/search/:search_str

Request:

  • :id - dataset id
  • :meta_type - name of metadata type or "features" to search features
  • :search_str - OPTIONAL search value to try and match

Response:

An array of strings, each one being a different option that matched the search value for the metadata type given. If no search value is provided, it will return the first 100 values. When a search value is provided, it will return a maximum of 100 values.

["option1","option2","option3"]

POST: /api/datasets/:id/samples

Request:

  • :id - dataset id

Post Body:

A valid Geney query as JSON. Note that you can leave the features and metaTypes arrays empty since we are only going to look at the filters to count the samples.

Response:

An integer, which is the number of samples that matched the given filters.

123

POST: /api/datasets/:id/download

Request:

  • :id - dataset id

Post Body:

Because we want the browser to download the response as a new file, we submit a form via a POST request that opens a new browser tab so we don't lose our work. Since we are submitting a form we cannot send our request as raw JSON, but as form data which is is essentially a list of key-value pairs. This endpoint requires there to be two keys query and options which are both simply JSON strings.

Response:

A subset of the initial dataset as requested via the query. It will include a Content-Disposition header to prompt the browser to download the response as a file rather than display it on the screen.

Clone this wiki locally