README.md

# 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/
`

## Specification

### 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.
* Example:
```
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 
* Example:
```
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
  * Example:
```
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
  * Example:
```
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
```	  
 
* Elements:
  * 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
```
    
* Reactions:
  * 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/
```    

* Data overlay
	* URL:	`/projects/{projectId}/overlays/{overlayId}/` 
	* 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/
```    

* 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/
```    

* 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
```

* Add overlay    
	* URL:	`/projects/{projectId}/overlays/` 
	* Method: POST
	* Parameters: TODO
	* Example:
```
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/
```    
    
    
### Users
* 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
```