This page gives detailed descriptions of some of the REST methods of dbNP. A more general overview of the RESTful services of dbNP is given on the modules page.

General properties of the REST calls

Note: the protocol described here does not adhere (yet) to RESTful principles, such as exposing different data types via different URL paths (e.g. /assay/34) or also using HTTP POST, PUT and DELETE actions. Converting all calls to proper RESTful conventions is still on the roadmap.

Authentication

Note that in the following examples, authentication arguments are omitted, but in all cases the following arguments should be supplied with the REST call:

sessionToken - a GSCF session token that authenticates the calling user (to be cross-validated with the parent GSCF of the module)

Note that most probably, the situation is as follows:
A user logs in to the parent GSCF of the module
The user requests assay data from the module
To fulfill this request, GSCF generates a one-time token to do the REST call on behalf of the user
GSCF initiates a server-side a call to the module, e.g. a getMeasurementData call, using the generated session token
At that point, the module is supposed to check with its parent GSCF (which in this example is also the calling GSCF) if the token is correct, and if so, return the data

Descriptions of mandatory REST methods of the Clean Data Module

getMeasurements

Returns a list of simple measurement tokens for an assay.

Parameters

assayToken - Has to be one assayToken for which all measurementsTokens  available are returned in a list.

Return value

List of measurement tokens. These are usually human readable short descriptors.

Example

Example REST call:
http://localhost:8182/sam/rest/getMeasurements/query?assayToken=PPSH-Glu-A

Resulting JSON object:
[ "sodium (Na+)", "potassium (K+)", "total carbon dioxide (tCO)" ]

getMeasurementMetaData

Return measurement metadata belonging to an assay.c

Parameters

assayToken - token for an assay for which the metadata is returned.

measurementToken - Measurement token for which the metadata is returned. This argument can occur either 0, 1, or more times. If the argument is not given,  all meatadata for the specified assay is returned.

Return value

List of measurement metadata. Each item of the list gives metadata fields of one measurement.

Examples

Example REST call:
http://localhost:8182/sam/rest/getMeasurementMetaData/query?assayToken=2&
measurementToken=total calcium (Ca)&
measurementToken=glucose

Resulting JSON object:
[ {"name":"glucose","unit":"mg/dl","referenceValues":null,"correctionMethod":null,"isDrug":false,"isIntake":false,"inSerum":false,"isNew":false},
{"name":"total calcium (Ca)","unit":"mg/dl","referenceValues":null,"correctionMethod":null,"isDrug":false,"isIntake":false,"inSerum":false,"isNew":false} ]

Example REST call without measurementTokens:
http://localhost:8182/sam/rest/getMeasurementMetaData/query?assayToken=PPSH-Glu-B

Resulting JSON object
[ {"name":"sodium (Na+)","unit":"mmol/l","referenceValues":null,"correctionMethod":null, "isDrug":false,"isIntake":false,"inSerum":false,"isNew":false},
{"name":"potassium (K+)","unit":"mmol/l","referenceValues":null,"correctionMethod":null,"isDrug":false,"isIntake":false,"inSerum":false,"isNew":false},
{"name":"total carbon dioxide (tCO)","unit":"mmol/l","referenceValues":null,"correctionMethod":null,"isDrug":false,"isIntake":false,"inSerum":false,"isNew":false} ]

getMeasurementData

Return list of measurement data for a set of samples and measurements belonging to a certain assay.

Parameters

assayToken - token identifying an assay to which all requested data belongs.

measurementToken - This argument restricts the returned data to the measurementTokens specified here. This argument may occure 0, 1 or more times. If this argument is not given, all samples for the measurementTokens are returned. Otherwise, the data for only those samples that belong to the specified measurementToken(s) is returned.
sampleToken - Restrict the returned data to the samples specified here. This argument may occur 0, 1 or more times. If this argument is not given, all samples for the measurementTokens are returned. Otherwise, the data for only the specified samples is returned.

verbose - If this argument is present and its value is "true", then the data is returned in a more redundant but also easier-to-process JSON format. By default, the data is returned in a compact representation (cf.'Return value'). In communication with GSCF, the verbose format is optional to implement, because GSCF currently only requests the standard non-verbose format.

Return value

The date is returned by default in a compact JSON object (see examples) representing a table, or, if the 'verbose' argument is set to true, as a list of triples of the form sampleToken x measurementToken x value.

The default (non-verbose) JSON object for the returned array is as follows.

The list contains three elements:

(1) a list of sampleTokens,
(2) a list of measurementTokens,
(3) a list of values.

The list of values is a matrix represented as a list. Each row of the matrix contains the values of a measurementToken (in the order given in the measurement token list, (2)). Each column of the matrix contains the values for the sampleTokens (in the order given in the list of sampleTokens, (1)). (cf. examples below.)


Examples

Example REST call:
http://localhost:8182/sam/rest/getMeasurementData/query?assayToken=PPSH-Glu-A&
measurementToken=total carbon dioxide (tCO)&
sampleToken=5_A&
sampleToken=1_A&
verbose=true

Resulting JSON object:
[ {"sampleToken":"1_A","measurementToken":"total carbon dioxide (tCO)","value":28},
{"sampleToken":"5_A","measurementToken":"total carbon dioxide (tCO)","value":29} ]

Example REST call without sampleToken, without measurementToken and without verbose representation:
http://localhost:8182/sam/rest/getMeasurementData/query?
assayToken=PPSH-Glu-A&
verbose=true

Resulting JSON object:
[ {"sampleToken":"1_A","measurementToken":"sodium (Na+)","value":139},
{"sampleToken":"1_A","measurementToken":"potassium (K+)","value":4.5},
{"sampleToken":"1_A","measurementToken":"total carbon dioxide (tCO)","value":26},
{"sampleToken":"2_A","measurementToken":"sodium (Na+)","value":136},
{"sampleToken":"2_A","measurementToken":"potassium (K+)","value":4.3},
{"sampleToken":"2_A","measurementToken":"total carbon dioxide (tCO)","value":28},
{"sampleToken":"3_A","measurementToken":"sodium (Na+)","value":139},
{"sampleToken":"3_A","measurementToken":"potassium (K+)","value":4.6},
{"sampleToken":"3_A","measurementToken":"total carbon dioxide (tCO)","value":27},
{"sampleToken":"4_A","measurementToken":"sodium (Na+)","value":137},
{"sampleToken":"4_A","measurementToken":"potassium (K+)","value":4.6},
{"sampleToken":"4_A","measurementToken":"total carbon dioxide (tCO)","value":26},
{"sampleToken":"5_A","measurementToken":"sodium (Na+)","value":133},
{"sampleToken":"5_A","measurementToken":"potassium (K+)","value":4.5},
{"sampleToken":"5_A","measurementToken":"total carbon dioxide (tCO)","value":29} ]

Example REST call with default compact view and without sampleToken:

http://localhost:8182/sam/rest/getMeasurementData/query?
assayToken=PPSH-Glu-A&
measurementToken=total carbon dioxide (tCO)

Resulting JSON object:
[ ["1_A","2_A","3_A","4_A","5_A"],
["sodium (Na+)","potassium (K+)","total carbon dioxide (tCO)"],
[139,136,139,137,133,4.5,4.3,4.6,4.6,4.5,26,28,27,26,29] ]

Explanation:
The default (non-verbose) JSON object is an array of three arrays.
The first nested array gives the sampleTokens for which data was retrieved.
The second nested array gives the measurementToken for which data was retrieved.
The third nested array gives the data for sampleTokens and measurementTokens.

Example REST call with default compact view and without sampleToken:
http://localhost:8182/sam/rest/getMeasurementData/query?
assayToken=PPSH-Glu-A&
measurementToken=total carbon dioxide (tCO)

Resulting JSON object:
[ ["1_A","2_A","3_A","4_A","5_A"],
["sodium (Na+)","potassium (K+)","total carbon dioxide (tCO)"],
[139,136,139,137,133,4.5,4.3,4.6,4.6,4.5,26,28,27,26,29] ]

Explanation:
The default (non-verbose) JSON object is an array of three arrays.
The first nested array gives the sampleTokens for which data was retrieved.
The second nested array gives the measurementToken for which data was retrieved.
The third nested array gives the data for sampleTokens and measurementTokens.

In this example, the matrix represents the values of the previous Example. The matrix looks like this:

	1_A	2_A	3_A	4_A	5_A
Na+	139	136	139	137	133
K+	4.5	4.3	4.6	4.6	4.5
tCO	26	282	27	26	29

getAssayURL

Return url for a specified assay. The url renders information on the assay on the Clean Data Module.

Parameters

assayToken - token for an assay for which to return the url.

Return value

A hash containing only one entry with key 'url' and the desired url as value.

Examples

Example REST call:
http://localhost:8182/sam/rest/getAssayURL/query?assayToken=PPSH-Glu-A

Resulting JSON object:
{"url":"http://localhost:8182/sam/SimpleAssay/show/1"}

Descriptions of REST methods of a data module for querying

getQueryableFields

Retrieves a list of fields that could be queried when searching for a specific entity.

Parameters

entity - name of the entity to retrieve a list of fields for. Might be 'Study', 'Assay', 'Sample' etc. Combinations of entities are also possible. If no entity is given, fields are returned for all entities.

Return value

A map with one entry per entity. The key is the entity name and the value is a list of field names.

Examples

Example REST call with one entity:
http://localhost:8184/metagenomics/rest/getQueryableFields?entity=Study

Resulting JSON object:
{"Study": [ "# sequences", "run name"] }

Example REST call with multiple entities:
http://localhost:8184/metagenomics/rest/getQueryableFields?entity=Study&entity=Sample

Resulting JSON object:
{"Study": [ "# sequences", "run name"], "Sample": [ "# sequences", "bacteria"]}

Example REST call without entities:
http://localhost:8184/metagenomics/rest/getQueryableFields

Resulting JSON object:
{"Study": [ "# sequences", "run name"], "Sample": [ "# sequences", "bacteria"], "Assay": []}

getQueryableFieldData

Returns data for the given field and entities.

Parameters

entity - Entity that is searched for. Might be 'Study', 'Assay', 'Sample' etc.

tokens - One or more tokens of the entities that the data should be returned for.

fields - One or more field names of the data to be returned. If no fields are given, all fields for the given entity/entities are returned

Return value

Map with keys being the entity tokens and the values being maps with entries [field] = [value]. Not all fields and tokens that are asked for have to be returned by the module (e.g. when a specific entity can not be found, or a value is not present for an entity)

Examples

Example REST call with multiple fields and tokens:
http://localhost:8184/metagenomics/rest/getQueryableFieldData?entity=Study&tokens=abc1&tokens=abc2&fields=# sequences&fields=# bacteria

Resulting JSON object (N.B. the field # bacteria is not found for the second object):
{ "abc1": { "# sequences": 141, "# bacteria": 0 }, "abc2": { "#sequences": 412 } }

Example REST call with non-existing object:
http://localhost:8184/metagenomics/rest/getQueryableFieldData?entity=Study&tokens=nonExisting&tokens=abc2&fields=# sequences

Resulting JSON object:
{ "abc2": { "#sequences": 412 } }

Example REST call without fields
http://localhost:8184/metagenomics/rest/getQueryableFieldData?entity=Study&tokens=abc2

Resulting JSON object (empty because entity is not given):
{ "abc2": { "#sequences": 412, "# bacteria": 3 } }

Example REST call without entity
http://localhost:8184/metagenomics/rest/getQueryableFieldData?tokens=nonExisting&tokens=abc2&fields=# sequences

Resulting JSON object (empty because entity is not given):
{}

getPossibleActions

Retrieves a list of actions that can be performed on data with a specific entity. This method is used when a query has been executed, to provide the user with actions to perform on the search result.

Parameters

entity - Entity that is searched for. Might be 'Study', 'Assay', 'Sample' etc. Might be more than one. If no entity is given, a list of actions for all entities is given.

Return value

Hashmap with keys being the entities and the values are lists with the action this module can perform on this entity. The actions as hashmaps themselves. The hashmap should contain:

name: unique name of this action. Is used to distinguish actions and used as a html class name for the links to the action. The class name could trigger a specific icon for the link.

description: description shown to the user. The description is postfixed with the module name, in order to distinguish between similar actions of different modules

url: url to call when the action should be performed. If left empty, the url will default to [moduleurl]/action/[actionname].

type: (optional) type of this action. Possible values are 'refine', 'export', 'default' or ''. If not specified, 'default' is used.

The action is performed when the user clicks on a link. The user will be redirected to the action url, and the following parameters are given:

actionName: The name of the action to be performed. This enables the possibility of having the same URL for different actions.

name: Name of the search that the action originated from. Particularly useful for refining searches.

url: URL of the search that the action originated from. Particularly useful for refining searches.

entity: The entity of objects that the action should be performed on. This enables the possibility of having the same URL for a similar action on different entities.

tokens: Entity tokens of the objects that the action should be performed on.

The action methods should support GET and POST calls.

Examples

Example REST call:
http://localhost:8184/metagenomics/rest/getPossibleActions?entity=Study

Resulting JSON object:
{ "Study": [ { "name": "excel", "type": "export", "description": "Export as excel", "url": "http://localhost:8184/metagenomics/study/exportAsExcel" }, { "name": "fasta", "type": "export","description": "Export as fasta", "url": "http://localhost:8184/metagenomics/study/exportAsFasta" } ] }

Example REST call without entity:
http://localhost:8184/metagenomics/rest/getPossibleActions

Resulting JSON object:
{ "Study": [ { "name": "excel", "type": "export","description": "Export as excel", "url": "http://localhost:8184/metagenomics/study/exportAsExcel" }, { "name": "fasta", "type": "export","description": "Export as fasta", "url": "http://localhost:8184/metagenomics/study/exportAsFasta" } ], "Sample": [ { "name": "fasta", "type": "export","description": "Export as fasta", "url": "http://localhost:8184/metagenomics/sample/exportAsFasta" }, { "name": "refine", "type": "refine","description": "Refine search by classification", "url": "http://localhost:8184/metagenomics/query/refineExternal" } ], "Assay": [] }

Example action call for studies with token 'ABC' and 'DEF'.

http://localhost:8184/metagenomics/study/exportAsExcel?actionName=excel&name=Search+1&url=http%3A%2F%2Flocalhost%3A8080%2Fgscf%2FadvancedQuery%2Fshow%2F3&entity=Study&tokens=ABC&tokens=DEF