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.
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=4llqer1n2ms298bkqmqet7q59m" 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=lfqldn2d9a5nksnkkfuqrcilhk" 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=lfqldn2d9a5nksnkkfuqrcilhk" 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=lfqldn2d9a5nksnkkfuqrcilhk" 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=gaceo10sovupaojseb2ui69igr" "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=gaceo10sovupaojseb2ui69igr" "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=lfqldn2d9a5nksnkkfuqrcilhk" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/models/*/bioEntities/elements/?columns=id,name,type
```
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
* 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=lfqldn2d9a5nksnkkfuqrcilhk" 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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" "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=gaceo10sovupaojseb2ui69igr" "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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" --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=gaceo10sovupaojseb2ui69igr" --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=gaceo10sovupaojseb2ui69igr" --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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" 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=gaceo10sovupaojseb2ui69igr" 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=h710fmgs3tpijv65gti44v4532" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203/
* URL: `/projects/{projectId}/overlays/{overlayId}/`
* Method: DELETE
* Parameters: TODO
* Example:
```
curl -X DELETE --cookie "MINERVA_AUTH_TOKEN=kl3aminujactlvadki2d6ce5gt" 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=kl3aminujactlvadki2d6ce5gt" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203:downloadSource
```
* Add overlay
* URL: `/projects/{projectId}/overlays/`
* 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=daehbfm21htm9kp09gvak1m3hk" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/
* User data
* URL: `/users/{login}/`
* Method: GET
* Parameters: TODO
* Example:
```
curl -X GET --cookie "MINERVA_AUTH_TOKEN=daehbfm21htm9kp09gvak1m3hk" http://pg-sandbox.uni.lu/minerva/api/users/testAdmin