Skip to content
Snippets Groups Projects
Commit f3bc2748 authored by Piotr Gawron's avatar Piotr Gawron
Browse files

documentation of REST API improved

parent 6f08588c
No related branches found
No related tags found
1 merge request!11Resolve "Rest API should follow google guidlines"
Hide whitespace changes
Inline Side-by-side
Showing
with 349 additions and 28 deletions
README.md
+ 334
− 16
View file @ f3bc2748
......@@ -6,27 +6,345 @@ Rest API is located in /api/ path of the deployed application. For instance, Res
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: TODO
* 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: TODO
* 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
* Example: `/projects/pdmap_feb17/`
* URL: `/projects/{projectId}/`
* Method: GET
* Parameters: TODO
* 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: TODO
* 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
```
* Elements:
* URL: `/projects/{projectId}/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: `/projects/pdmap_feb17/bioEntities/elements/?columns=id,name,type`
* 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
```
* Reactions:
* URL: `/projects/{projectId}/bioEntities/reactions/`
* Method: GET
* Parameters:
* `columns` - set of columns. Possible values are:
* `ids` - set of database ids
* Example: `/projects/pdmap_feb17/bioEntities/reactions/?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=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: POST
* Parameters: TODO
* Example:
```
TODO
```
* Remove overlay
* URL: `/projects/{projectId}/overlays/{overlayId}`
* Method: PATCH
* Parameters: TODO
* Example:
```
TODO
```
* Download source
* URL: `/projects/{projectId}/overlays/{overlayId}:downloadSource`
* Method: GET
* Parameters: TODO
* Example:
```
TODO
```
* Add overlay
* URL: `/projects/{projectId}/overlays/`
* Method: GET
* Parameters: TODO
* Example:
```
TODO
```
### Users
### Configuration
\ No newline at end of file
* User data
* URL: `/users/{login}/`
* Method: GET
* Parameters: TODO
* Example:
```
TODO
```
\ No newline at end of file
rest-api/src/main/java/lcsb/mapviewer/api/genomics/ReferenceGenomeController.java
+ 1
− 1
View file @ f3bc2748
......@@ -25,7 +25,7 @@ public class ReferenceGenomeController extends BaseController {
produces = { MediaType.APPLICATION_JSON_VALUE })
public ReferenceGenomeView getDrugsByQuery(//
@CookieValue(value = Configuration.AUTH_TOKEN) String token, //
@PathVariable(value = "organism") String organism, //
@PathVariable(value = "organismId") String organism, //
@PathVariable(value = "type") String type, //
@PathVariable(value = "version") String version//
) throws SecurityException, QueryException {
......
rest-api/src/main/java/lcsb/mapviewer/api/projects/ProjectController.java
+ 1
− 1
View file @ f3bc2748
......@@ -83,7 +83,7 @@ public class ProjectController extends BaseController {
@RequestParam(value = "backgroundOverlayId", defaultValue = "") String backgroundOverlayId, //
@RequestParam(value = "overlayIds", defaultValue = "") String overlayIds, //
@RequestParam(value = "zoomLevel", defaultValue = "") String zoomLevel, //
@RequestParam(value = "polygonString") String polygonString//
@RequestParam(value = "polygonString", defaultValue = "") String polygonString//
) throws SecurityException, QueryException, IOException, InvalidColorSchemaException, CommandExecutionException, ConverterException,
InconsistentModelException {
......
rest-api/src/main/java/lcsb/mapviewer/api/projects/ProjectRestImpl.java
+ 0
− 7
View file @ f3bc2748
......@@ -266,7 +266,6 @@ public class ProjectRestImpl extends BaseRestImpl {
Double minY = originalModel.getHeight();
Double maxX = 0.0;
Double maxY = 0.0;
if (!polygonString.equals("")) {
Path2D polygon = cc.latLngToPolygon(polygonString);
PathIterator pathIter = polygon.getPathIterator(null);
......@@ -280,12 +279,6 @@ public class ProjectRestImpl extends BaseRestImpl {
}
pathIter.next();
}
} else {
maxX = originalModel.getWidth();
maxY = originalModel.getHeight();
minX = 0.0;
minY = 0.0;
}
maxX = Math.min(originalModel.getWidth(), maxX);
maxY = Math.min(originalModel.getHeight(), maxY);
......
rest-api/src/main/java/lcsb/mapviewer/api/users/UserController.java
+ 1
− 1
View file @ f3bc2748
......@@ -66,7 +66,7 @@ public class UserController extends BaseController {
}
}
@RequestMapping(value = "/users/{login}", method = { RequestMethod.GET, RequestMethod.POST }, produces = { MediaType.APPLICATION_JSON_VALUE })
@RequestMapping(value = "/users/{login}", method = { RequestMethod.GET}, produces = { MediaType.APPLICATION_JSON_VALUE })
public Map<String, Object> getUser(//
@CookieValue(value = Configuration.AUTH_TOKEN) String token, //
@PathVariable(value = "login") String login, //
......
service/src/main/java/lcsb/mapviewer/services/utils/gmap/CoordinationConverter.java
+ 12
− 2
View file @ f3bc2748
......@@ -79,6 +79,10 @@ public final class CoordinationConverter implements Serializable {
*/
private final Point2D pixelOrigin;
private Double width;
private Double height;
/**
* Bounds value in the optMin, optMax range.
*
......@@ -124,6 +128,8 @@ public final class CoordinationConverter implements Serializable {
pixelOrigin = new Point2D.Double(tileSize / 2, tileSize / 2);
pixelsPerLonDegree = tileSize / FULL_ANGLE_IN_DEGREES;
pixelsPerLonRadian = tileSize / (2 * Math.PI);
width = model.getWidth();
height = model.getHeight();
}
/**
......@@ -176,7 +182,6 @@ public final class CoordinationConverter implements Serializable {
* @return polygon in absolute coordinates
*/
public Path2D latLngToPolygon(String latLngPolygon) {
Path2D result = new Path2D.Double();
String[] latLngArray = latLngPolygon.split(";");
List<Point2D> points = new ArrayList<>();
......@@ -192,8 +197,13 @@ public final class CoordinationConverter implements Serializable {
}
}
if (points.size() <= 2) {
throw new InvalidArgumentException("Invalid polygon string. It should contain at least 3 points, but found: " + latLngPolygon);
points.clear();
points.add(new Point2D.Double(0, 0));
points.add(new Point2D.Double(width, 0));
points.add(new Point2D.Double(width, height));
points.add(new Point2D.Double(0, height));
}
Path2D result = new Path2D.Double();
result.moveTo(points.get(0).getX(), points.get(0).getY());
for (int i = 1; i < points.size(); i++) {
Point2D point = points.get(i);
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment