Newer
Older
# Rest API (version 11)
## Introduction
Rest API is located in /api/ path of the deployed application. For instance, Rest API of pdmap project that can be browsed using http://pdmap.uni.lu/minerva/ will be located here: http://pdmap.uni.lu/minerva/api/
Rest API tries to follow [API Design Guide](https://cloud.google.com/apis/design/) by Google.
All API calls (except login) must include MINERVA_AUTH_TOKEN obtained due login process.
## Quickstart guide
To use API first we need to login:
`curl -X POST -c - --data "login=anonymous&password=" http://pg-sandbox.uni.lu/minerva/api/doLogin`
```
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 55 0 55 0 0 1774 0 --:--:-- --:--:-- --:--:-- 1774{"info":"Login successful. TOKEN returned as a cookie"}# Netscape HTTP Cookie File
# https://curl.haxx.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.
localhost FALSE / FALSE 1496934071 MINERVA_AUTH_TOKEN xxxxxxxx
```
The response creates an authentication token and puts it into a cookie `MINERVA_AUTH_TOKEN=xxxxxxxx`. When using console curl command this cookie must be attached to every query that follows.
When we have authentication token we can access information about december release of PD map project:
`
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/
`
### Authentication
* Login:
* URL: `/doLogin`
* Method: POST
* Parameters:
* `login` - user login, 'anonymous' can be used for accessing api with guest account access level
* `password` - user passwod, for guest account this field is optional
* Output. If login operation is successfull then `MINERVA_AUTH_TOKEN` cookie will be created with authentication token. If credentails are invalid response with `403` status code will be returned. Token will be valid for the next 120 minutes.
* Example:
```
curl -X POST -c - --data "login=anonymous&password=" http://pg-sandbox.uni.lu/minerva/api/doLogin
```
* Login:
* URL: `/doLogout`
* Method: POST
* Example:
```
curl -X POST -c - http://pg-sandbox.uni.lu/minerva/api/doLogout
```
### Configuration
* URL: `/configuration/`
* Method: GET
* Parameters: *NONE*
* Output: List of all minerva configuration details.
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/configuration/
```
### Genomics
* URL: `/genomics/taxonomies/{organismId}/genomeTypes/{type}/versions/{version}/`
* Method: GET
* Parameters:
* organismId - identifier of the organism in taxonomy db
* type - type of genome (database from which reference genome should be used), for now only UCSC is supported
* version - version of the reference genome
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/genomics/taxonomies/9606/genomeTypes/UCSC/versions/hg19/
### Projects
* Project data:
* URL: `/projects/{projectId}/`
* Method: GET
* Parameters:
* projectId - identifier of the project
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/
```
* Source file:
* URL: `/projects/{projectId}:downloadSource`
* Method: GET
* Parameters:
* projectId - identifier of the project
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_jun16:downloadSource --output some.file
```
#### (sub)Maps
* Download map as a model file (ie. in CellDesigner format)
* URL: `/projects/{projectId}/models/{modelId}:downloadModel`
* Method: GET
* Parameters: TODO,
* See also `/configuration/` query to get list of possible formats
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" "http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/models/15305:downloadModel?handlerClass=lcsb.mapviewer.converter.model.celldesigner.CellDesignerXmlParser" --output some.file
```
* Download map as an image
* URL: `/projects/{projectId}/models/{modelId}:downloadImage`
* Method: GET
* Parameters: TODO,
* See also `/configuration/` query to get list of possible formats
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" "http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/models/15305:downloadImage?handlerClass=lcsb.mapviewer.converter.graphics.PngImageGenerator" --output some.file
* URL: `/projects/{projectId}/models/{modelId}/bioEntities/elements/`
* Method: GET
* Parameters:
* `columns` - set of columns. Possible values are: id, modelId, name, type, description, symbol, complexId, compartmentId, fullName, abbreviation, formula, name, synonyms, formerSymbols, references, bounds, hierarchyVisibilityLevel,
* `ids` - set of database ids
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/models/*/bioEntities/elements/?columns=id,name,type
* URL: `/projects/{projectId}/models/{modelId}/bioEntities/reactions/`
* Method: GET
* Parameters:
* `columns` - set of columns. Possible values are:
* `ids` - set of database ids
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/models/*/bioEntities/reactions/?columns=id,name,type
```
* Search:
* URL: `/projects/{projectId}/models/{modelId}/bioEntities:search`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/models/*/bioEntities:search?query=SNCA
```
* Suggested search queries:
* URL: `/projects/{projectId}/models/{modelId}/bioEntities/suggestedQueryList`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/models/*/bioEntities/suggestedQueryList
```
#### Chemicals
* URL: `/projects/{projectId}/chemicals:search`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" "http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/chemicals:search?query=rotenone"
```
#### Comments
* List comments
* URL: `/projects/{projectId}/comments/models/{modelId}/`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" "http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/comments/models/*/"
```
* Reaction comments
* URL: `/projects/{projectId}/comments/models/{modelId}/bioEntities/reactions/{reactionId}`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/comments/models/15305/bioEntities/reactions/187811/
```
* Element comments
* URL: `/projects/{projectId}/comments/models/{modelId}/bioEntities/elements/{elementId}`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/comments/models/15305/bioEntities/elements/431868/
```
* Point comments
* URL: `/projects/{projectId}/comments/models/{modelId}/points/{coordinates}`
* Method: GET
* Parameters: TODO
* Example: TODO
* Create element comment
* URL: `/projects/{projectId}/comments/models/{modelId}/bioEntities/elements/{elementId}`
* Method: POST
* Parameters: TODO
* Example:
```
curl -X POST --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" --data "name=testComment&email=a@a.pl&content=someCont&coordinates=1,2" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/comments/models/15305/bioEntities/elements/431868/
```
* Create reaction comment
* URL: `/projects/{projectId}/comments/models/{modelId}/bioEntities/reactions/{reactionId}`
* Method: POST
* Parameters: TODO
* Example:
```
curl -X POST --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" --data "name=testComment&email=a@a.pl&content=someCont&coordinates=1,2" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/comments/models/15305/bioEntities/reactions/187811
```
* Create coordinates comment
* URL: `/projects/{projectId}/comments/models/{modelId}/points/{coordinates}`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X POST --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" --data "name=testComment&email=a@a.pl&content=someCont" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/comments/models/15305/points/1.00,2.00
```
#### Drugs
* URL: `/projects/{projectId}/drugs:search`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/drugs:search?query=aspirin
```
#### MiRNAs
* URL: `/projects/{projectId}/miRnas:search`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/miRnas:search?query=hsa-miR-125a-3p
```
#### Publications
* URL: `/projects/{projectId}/models/{modelId}/publications/`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/models/*/publications/
```
#### Data overlays
* List user data overlays
* URL: `/projects/{projectId}/overlays/`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/
* Add overlay
* URL: `/projects/{projectId}/overlays/`
* Method: POST
* Parameters:
* name - name of the data overlay
* content - content of the file that is uploaded with definition what should be visible where
* description - short desription of the data overlay
* filename - name of the file that should be used when downloading the source
curl -X POST --data "content=name%09color%0ACAPN1%09%2300FF00%0APARK7%09%23AC0000&description=test%20desc&filename=test.txt&name=test%20nam" --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/
* Update overlay
* URL: `/projects/{projectId}/overlays/{overlayId}/`
* Method: PATCH
* Parameters: TODO
* Example:
```
curl -X PATCH --data "{\"overlay\":{\"name\":\"test\", \"description\":\"test2\"}}" --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203/
* Remove overlay
* URL: `/projects/{projectId}/overlays/{overlayId}/`
* Method: DELETE
* Parameters: TODO
* Example:
```
curl -X DELETE --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203/
* Download source
* URL: `/projects/{projectId}/overlays/{overlayId}:downloadSource`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203:downloadSource
```
* URL: `/projects/{projectId}/overlays/{overlayId}/`
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203/
* bioEntities (Elements and reactions)
* URL: `/projects/{projectId}/overlays/{overlayId}/models/{modelId}/bioEntities/`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203/models/*/bioEntities/
* Reaction
* URL: `/projects/{projectId}/overlays/{overlayId}/models/{modelId}/bioEntities/reactions/{reactionId}/`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203/models/15305/bioEntities/reactions/187811/
```
* Element
* URL: `/projects/{projectId}/overlays/{overlayId}/models/{modelId}/bioEntities/elements/{elementId}/`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203/models/15305/bioEntities/elements/431433/
* User data
* URL: `/users/{login}/`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/users/testAdmin
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
# JavaScript API (version 11). Unstable dev API.
Minerva visualization is created by including `minerva.js` and calling `minerva.create({element:divElement})` method. This method returns a Promise which will resolve to the object that allows custom JS manipulation.
## Specification
* `getVisibleDataOverlays()`
* Description: Returns a Promise with list of visible overlays
* Arguments: NONE
* Example:
```
customMap.getVisibleDataOverlays().then(function(overlays){console.log(overlays);});
```
* `addListener({dbOverlayName, type, callback})`
* Description: Adds a listener to database connector like drug database.
* Arguments:
* dbOverlayName - string representing database for which we want to register listener, available databases are: `search`, `drug`, `chemical`, `mirna`, `comment`
* type - type of the event, supported db Events are: `onSearch`
* callback - callback method
* Example
```
customMap.addListener({dbOverlayName:"search",type:"onSearch", callback:function(res){console.log(res);}});
```
* `getHighlightedBioEntities(dbOverlayName)`
* Description: returns a promise with list of elements that are currently highlight by the specufuc database
* Arguments: dbOverlayName - string representing database for which we want to register listener, available databases are: `search`, `drug`, `chemical`, `mirna`, `comment`
* Example:
```
customMap.getHighlightedBioEntities("search").then(function(elements){console.log(elements);});
```
* `getProject()`
* Description: Returns object with information about visualized disease map project.
* Arguments: NONE
* Example:
```
customMap.getProject()
```
* `getConfiguration()`
* Description: Returns a promise with configuration information obtained from server. Configuration information include configuration options (like default visible map), supported formats, etc.
* Arguments: NONE
* Example:
```
customMap.getConfiguration().then(function(configuration){console.log(configuration);});
```
* `getBioEntityById({id, modelId, type})`
* Arguments: TODO
* Example:
```
TODO
```
* `getReactionsWithElement(element)`
* Arguments: TODO
* Example:
```
TODO
```
* `showBioEntity({element, type, options})`
* Arguments: TODO
* Example:
```
TODO
```
* `hideBioEntity({element, type})`
* Arguments: TODO
* Example:
```
TODO
```
* `setCenter({modelId, x, y})`
* Arguments: TODO
* Example:
```
TODO
```
* `fitBounds({modelId, x1, y1, x2, y2})`
* Arguments: TODO
* Example:
```
TODO
```
* `setCenter({modelId, x, y})`
* Arguments: TODO
* Example:
```
TODO
```