You are in REST API » v11.x.x || Go to

Rest API

Table of contents

• Introduction
• QuickStart guide
• Specification
  • Authentication
  • Configuration
  • Genomics
  • Projects
    • (sub)Maps
    • Chemicals
    • Comments
    • Drugs
    • MiRNAs
    • Publications
    • Data overlays
  • Users

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 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 password, for guest account this field is optional
  • Output. If login operation is successful then MINERVA_AUTH_TOKEN cookie will be created with authentication token. If credentials 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
    

• Logout:
  • URL: /doLogout
  • Method: POST
    • Parameters: NONE
  • 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

• List of (sub)maps in a project
  • URL: /projects/{projectId}/models/
  • 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/models/"
    

• Download map as a model file (i.e. in CellDesigner format)
  • URL: /projects/{projectId}/models/{modelId}:downloadModel
  • Method: GET
  • Parameters:
    * projectId - identifier of the project * modelId - identifier of the (sub)map in the project * handlerClass - class preparing model file. For list of all possible values check /configuration/ response. * polygonString (*) - polygon defining part of the model for downloading
  • 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: * projectId - identifier of the project * modelId - identifier of the (sub)map in the project * handlerClass - class preparing image file. For list of all possible values check /configuration/ response. * backgroundOverlayId (*) - identifier of the overlay used as a background overlay when creating image * overlayIds (*) - comma separated list of overlay identifiers that should be included in the image * zoomLevel (*) - zoom level at which image should be generated (min value used by default) * polygonString (*) - polygon defining part of the model for downloading
  • 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: * projectId - identifier of the project * modelId - identifier of the (sub)map in the project or wildcard ‘*’ character * columns (*) - set of columns (optional). 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 (optional)
  • 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:
    • projectId - identifier of the project
      • modelId - identifier of the (sub)map in the project or wildcard ‘*’ character
    • columns (*) - set of columns. Possible values are: id, reactionId, modelId, type, lines, centerPoint, products, reactants, modifiers, hierarchyVisibilityLevel, notes
    • ids (*) - set of database ids
    • participantId (*) - identifier of the element that should be part of the reaction
  • 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:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project or wildcard ‘*’ character
    • query (*) - search term identifying bioEntity
    • coordinates (*) - coordinates where bioEntity should be located
    • count (*) - max number of bioEntities to return
    • perfectMatch (*) - true when true query must be matched exactly, if false similar results are also acceptable
  • 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
  • Output: List of suggested queries for search mechanism.
  • 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/models/*/bioEntities/suggestedQueryList
    

Chemicals

• URL: /projects/{projectId}/chemicals:search
• Method: GET
• Parameters:
  • projectId - identifier of the project
  • columns (*) - set of columns for each result. Possible values are: name, references, description, directEvidenceReferences, directEvidence, synonyms, id, targets,
  • query (*) - chemical name
  • target (*) - target for which we are looking for chemicals. Target is defined as TYPE:ID. For example “ALIAS:534” is searching for chemicals that target Alias with id=534.
• 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:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project or wildcard ‘*’ character
    • columns (*) - set of columns for each result. Possible values are: title, type, content, removed, coord, modelId, elementId, id, pinned, author, email,
    • removed (*) - if defined then removed parameter must match.
  • 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:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project or wildcard ‘*’ character
    • reactionId - identifier of the reaction
    • columns (*) - set of columns for each result. Possible values are: title, type, content, removed, coord, modelId, elementId, id, pinned, author, email,
    • removed (*) - if defined then removed parameter must match.
  • 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:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project or wildcard ‘*’ character
    • elementId - identifier of the element
    • columns (*) - set of columns for each result. Possible values are: title, type, content, removed, coord, modelId, elementId, id, pinned, author, email,
    • removed (*) - if defined then removed parameter must match.
  • 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:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project or wildcard ‘*’ character
    • coordinates - coordinates of the point on (sub)map
    • columns (*) - set of columns for each result. Possible values are: title, type, content, removed, coord, modelId, elementId, id, pinned, author, email,
    • removed (*) - if defined then removed parameter must match.
  • Example: TODO
• Create element comment
  • URL: /projects/{projectId}/comments/models/{modelId}/bioEntities/elements/{elementId}
  • Method: POST
  • Parameters:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project
    • elementId - identifier of the element to be commented
    • name - name of the author
    • email - email of the author
    • content - content of the comment
    • pinned (*) - when true comment will be visible for others, if false then nobody except of admin will see it
    • coordinates - coordinates where comment is placed
  • 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:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project
    • reactionId - identifier of the reaction
    • name - name of the author
    • email - email of the author
    • content - content of the comment
    • pinned (*) - when true comment will be visible for others, if false then nobody except of admin will see it
    • coordinates - coordinates where comment is placed
  • 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:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project
    • name - name of the author
    • email - email of the author
    • content - content of the comment
    • pinned (*) - when true comment will be visible for others, if false then nobody except of admin will see it
    • coordinates - coordinates where comment is placed
  • 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:
  • projectId - identifier of the project
  • columns (*) - set of columns for each result. Possible values are: name, references, description, bloodBrainBarrier, brandNames, synonyms, id, targets,
  • query (*) - drug name or synonym
  • target (*) - target for which we are looking for drugs. Target is defined as TYPE:ID. For example “ALIAS:534” is searching for drugs that target Alias with id=534.
• 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:
  • projectId - identifier of the project
  • columns (*) - set of columns for each result. Possible values are: name, id, targets,
  • query (*) - miRNA id
  • target (*) - target for which we are looking for micro RNAs (miRNAs). Target is defined as TYPE:ID. For example “ALIAS:534” is searching for miRNAs that target Alias with id=534.
• 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:
  • projectId - identifier of the project
  • modelId - identifier of the (sub)map in the project or wildcard ‘*’ character
  • start (*) - first element to be return when pagination is on (default 0)
  • length (*) - how many publication we want to retrieve (default 10)
• 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:
    • projectId - identifier of the project
  • 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:
    • projectId - identifier of the project
    • name - name of the data overlay
    • content - content of the file that is uploaded with definition what should be visible where
    • description - short description of the data overlay
    • filename - name of the file that should be used when downloading the source
    • googleLicenseConsent - true/false indicating if user agreed to the new Google Maps API license https://cloud.google.com/maps-platform/terms/
  • Example:

    curl -X POST --data "content=name%09color%0ACAPN1%09%2300FF00%0APARK7%09%23AC0000&description=test%20description&filename=test.txt&name=test%20name&googleLicenseConsent=true" --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:
    • projectId - identifier of the project
    • overlayId - identifier of data overlay
  • Body: json with updated overlay

{   “overlay”: {     “name” : name,     “description” : description   } }

* 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:
    • projectId - identifier of the project
    • overlayId - identifier of data overlay
  • 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:
    • projectId - identifier of the project
    • overlayId - identifier of data overlay
  • Example:

    curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/projects/pdmap_dec15/overlays/3203:downloadSource
    

• Data overlay details
  • URL: /projects/{projectId}/overlays/{overlayId}/
  • Method: GET
  • Parameters:
    • projectId - identifier of the project
    • overlayId - identifier of data overlay
  • 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:
    • projectId - identifier of the project
    • overlayId - identifier of data overlay
  • 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:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project
    • overlayId - identifier of data overlay
    • reactionId - identifier of the reaction
  • 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:
    • projectId - identifier of the project
    • modelId - identifier of the (sub)map in the project
    • overlayId - identifier of data overlay
    • elementId - identifier of the element
  • 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/
    

Users

• User data
  • URL: /users/{login}/
  • Method: GET
  • Parameters:
    • login - user login
  • Example:

    curl -X GET --cookie "MINERVA_AUTH_TOKEN=xxxxxxxx" http://pg-sandbox.uni.lu/minerva/api/users/testAdmin