RESTful API to cBioPortal/cbioportal sessions in MongoDB.
Session information is stored in JSON, so this API generalizes to any JSON objects.
docker-compose up
You can also run it in detached mode with:
docker-compose up -d
In that case, to stop it one runs:
docker-compose down
If you want to rebuild the session service image after having made changes in development:
docker-compose up --build
Check http://localhost:8080/info to confirm session service is running. It should show a version number.
Test whether a session can be created like this:
curl -H "Content-Type: application/json" --user user:pass -X POST http://localhost:8080/api/sessions/test_portal/main_session --data '{"title": "my main portal session", "description": "this is an example"}'
The mongo database port is not exposed by default. One can connect to the mongo database like this:
docker exec -it session-service_db_1 mongo mongodb://localhost:27017
JDK 1.7 or later: http://www.oracle.com/technetwork/java/javase/downloads/index.html
Maven 3.0+: http://maven.apache.org/download.cgi
MongoDB: https://docs.mongodb.org/manual/
Create database 'session_service' using the 'mongo' shell interface to MongoDB:
$ mongo
> use session_service
Clone repository, compile, run tests, and start server:
$ git clone https://github.com/cBioPortal/session-service.git
$ cd session-service
session-service$ mvn package -Dpackaging.type=jar && java -Dspring.data.mongodb.uri=mongodb://localhost:27017/session-service -jar target/session_service-0.1.0.jar
To generate war file with a configuration file:
$ cd session-service
session-service$ mkdir src/main/resources/
session-service$ cp /path/to/myapp.config src/main/resources/
session-service$ mvn package
An example properties file:
spring.data.mongodb.database=session_service
spring.data.mongodb.host=localhost
spring.data.mongodb.port=27017
To have a context root that is not "/", add to the properties file:
server.contextPath=/session_service
server.port=8080 # change this if u want to use a different port
One can use session-service with or without basic authentication. It's disabled by default. To enable basic authentication set:
security.basic.enabled=true
spring.security.user.name=user
spring.security.user.password=pass
By default the server runs on port 8080. This can be overridden by setting the process's SERVER_PORT environment variable.
session-service$ export set SERVER_PORT=8090; mvn package -Dpackaging.type=jar && java -Dspring.data.mongodb.uri=mongodb://localhost:27017/session-service -jar target/session_service-0.1.0.jar
Sentry is already included as a dependency of this project, one can add the following this Sentry official documentation to enable sentry. For example, for Run without docker, add the following when starting the server:
-Dsentry.dsn=https://[email protected]/0
And example command for Run with docker also included in the docker-compoase.yaml file, please refer that command to enable sentry.
Swagger documentation will be found here: http://[url]:[port]/swagger-ui.html e.g. http://localhost:8090/swagger-ui.html
If basic auth is enabled note that one should pass the username password to access these endpoints e.g. with curl:
curl --user user:pass
| Type | Description |
|---|---|
| main_session | represent result's page query |
| virtual_study | represent a subset for samples saved from study summary page |
| group | similar to virtual study except its used in comparison page |
| comparison_session | represent comparison page query |
| settings | represent cbio page settings. page type is identified by a field page in it |
| custom_data | holds study-view page custom charts data |
| genomic_chart | represents genomic chart added by user in study-view page |
| custom_gene_list | represents custom gene list added by user in query page |
Creates a session. Returns status 200 and the session id in response body on success. The session is saved in a collection named {type}. Both source and type are saved in the session document. If a session with the same source, type, and data already exists in the database returns the session id of that session instead of creating a duplicate.
WARNING: This is case sensitive. You should always use the same case for source and type.
Example body for POST http://localhost:8080/api/sessions/msk_portal/main_session/
{"title": "my main portal session", "description": "this is an example"}
Example response:
{
"id": "57167a52ef86d81afb415aba"
}
If no JSON data passed in request body or an invalid type is sent returns 400 status with something like the following in the body:
{
"timestamp": 1461093154793,
"status": 400,
"error": "Bad Request",
"exception": "org.springframework.web.method.annotation.MethodArgumentTypeMismatchException",
"message": "valid types are: main_session, virtual_study, group, comparison_session, custom_data, genomic_chart",
"path": "/api/sessions/msk_portal/invalid_type/"
}
Sending invalid JSON in the request body returns a 400 status with something like the following in the body:
{
"timestamp": 1461090997119,
"status": 400,
"error": "Bad Request",
"exception": "org.cbioportal.session_service.domain.exception.SessionInvalidException",
"message": "\n{\"portal-session\": blah blah blah}\n ^",
"path": "/api/sessions/msk_portal/main_session/"
}
Returns all sessions for source and type. Returns "[]" if no sessions.
Example response for GET http://localhost:8080/api/sessions/msk_portal/main_session/
[
{
"id": "57167a52ef86d81afb415aba",
"data": {
"title": "my main portal session",
"description": "this is an example"
},
"source": "msk_portal",
"type": "main_session"
},
{
"id": "57167c69ef86fdfcec850342",
"data": {
"title": "my main portal session",
"description": "this is another example"
},
"source": "msk_portal",
"type": "main_session"
}
]
Returns single session given source, type, and id. Example response for GET http://localhost:8080/api/sessions/msk_portal/main_session/57167a52ef86d81afb415aba
{
"id": "57167a52ef86d81afb415aba",
"data": {
"title": "my main portal session",
"description": "this is an example"
},
"source": "msk_portal",
"type": "main_session"
}
If no session is found returns status 404 with a request body like this:
{
"timestamp": 1462379207301,
"status": 404,
"error": "Not Found",
"exception": "org.cbioportal.session_service.service.exception.SessionNotFoundException",
"message": "Session not found",
"path": "/api/sessions/msk_portal/main_session/test"
}
WARNING: This is case sensitive. GET http://localhost:8080/api/sessions/MSK_portal/main_session/57167a52ef86d81afb415aba and GET http://localhost:8080/api/sessions/msk_portal/Main_Session/57167a52ef86d81afb415aba are NOT equivalent.
Returns all sessions matching a query for source and type. Returns 200 status on success. Example response for GET http://localhost:8080/api/sessions/msk_portal/main_session/query?field=data.title&value=my%20main%20portal%20session
[
{
"id": "57167c69ef86fdfcec850342",
"data": {
"title": "my main portal session",
"description": "this is another example"
},
"source": "msk_portal",
"type": "main_session"
}
]
Creates a session given the source, type, and the session data in the request body. Returns status 200 and the session data in the response body.
Creates a session given the source, type, custom id (you can give user readable names), and the session data in the request body. Returns status 200 and the session data in the response body.
Updates a session given the source, type, and id. Returns status 200 on success with empty request body. Example body for PUT http://localhost:8080/api/sessions/msk_portal/main_session/57167a52ef86d81afb415aba
{
"title": "my UPDATED main portal session",
"description": "this is an example"
}
If no JSON data passed in request body returns status 400 with a request body like this:
{
"timestamp": 1461092375741,
"status": 400,
"error": "Bad Request",
"exception": "org.springframework.http.converter.HttpMessageNotReadableException",
"message": "Required request body is missing: public void org.cbioportal.session_service.web.SessionServiceController.updateSession(java.lang.String,java.lang.String,java.lang.String,java.lang.String)",
"path": "/api/sessions/msk_portal/main_session/57167a52ef86d81afb415aba"
}
If an invalid id is passed returns status 404 with a request body like this:
{
"timestamp": 1462379078498,
"status": 404,
"error": "Not Found",
"exception": "org.cbioportal.session_service.service.exception.SessionNotFoundException",
"message": "Session not found",
"path": "/api/sessions/msk_portal/main_session/test"
}
Sending invalid JSON in the request body returns a 400 status with something like the following in the body:
{
"timestamp": 1461092440979,
"status": 400,
"error": "Bad Request",
"exception": "org.cbioportal.session_service.domain.exception.SessionInvalidException",
"message": "\n{\n \"title\": \"my UPDATED main portal session\",\n \"description\": blah blah blah\n}\n ^",
"path": "/api/sessions/msk_portal/main_session/57167a52ef86d81afb415aba"
}
Deletes a session with source, type, and id. Returns 200 status on success with empty request body. Example URL for DELETE http://localhost:8080/api/sessions/msk_portal/main_session/57167c69ef86fdfcec850342
If an invalid id is passed returns status 404 with a request body like this:
{
"timestamp": 1462379146105,
"status": 404,
"error": "Not Found",
"exception": "org.cbioportal.session_service.service.exception.SessionNotFoundException",
"message": "Session not found",
"path": "/api/sessions/msk_portal/main_session/test"
}