cPathSquaredWebService

cPath2 Web API (design)

Introduction

We will use Spring Web @MVC to implement the web services. Web methods will return results in BioPAX, XML, or a text format.

Common URL prefix (the endpoint URL) will be http://www.pathwaycommons.org/pc2/ (in production). Unless explicitly specified, both GET and POST HTTP requests will be supported. POST method is preferred, especially for queries that accept multiple URIs.

We can also have multiple servlets for the same controllers, resolved by the extention, e.g., /search.xml to return XML, and /search.json to return JSON.

Normally, web services are not supposed to be used from web browsers, except for trivial/test cases. (Otherwise, one should manually encode URI and other query parameter values, such as "HTTP://WWW.REACTOME.ORG/BIOPAX#SIGNALING\_BY\_BMP\_1\_9606" to "HTTP:%2f%2fWWW.REACTOME.ORG%2fBIOPAX%23SIGNALING_BY_BMP_1_9606" and sometimes use 'View/View Page Source' menu to see the result.)

URIs are case sensitive.

Commands and Parameters

Handlers for each identified web service:

• get: Get Element (or a Sub-Model) by URI(s) or ID(s)

  • Parameters:
    • uri (multiple uris can be send as: uri=a&uri=b&... or via POST method)
    • format - by default, BioPAX L3, else - binary SIF, extended binary SIF, GSEA (.gmt), SBGN. Note: if id points to a protein record, it would not make sense to ask for GSEA or SBGN...
  • Output: based on format parameter

• search: Free (Full-Text) Text Search

  • Parameters:
    • q - keywords, wildcards, or Lucene query
    • type - a BioPAX class (to filter results)
    • organism - filter by organism (array); each value can be, e.g., "9606" (preferred), "http://identifiers.org/taxonomy/9606" or "Homo%20sapiens"
    • datasource - filter by data source: array of standard names (preferred) or URIs;
  • Output: XML/JSON object with ranked list of search hits

Note: optionally, if search returns no results, the "second query" may be performed that search Warehouse and may also include id-mapping.

• graph: Graph Query

  • Parameters:
    • source (multiple URIs or IDs can be send as: source=a&source=b&... or via POST method)
    • target (multiple uris can be send as: dest=a&dest=b&... or via POST method)
    • kind (neighborhood, common upstream, common downstream, common target, network of interest, k-shortest path)
    • limit
    • direction
    • format - by default, BioPAX L3, else binary SIF, extended binary SIF, GSEA (.gmt), or SBGN.
    • organism - filter by organism (array)
    • datasource - filter by data source (array)
  • Output: based on format parameter

• traverse: Traverse (Get Values Using a BioPAX Property Path)

  • Parameters:
    • uri - multiple ID values (array) is ok: uri=a&uri=b&... or - via POST method
    • path - a BioPAX property access path (alike XPath for BioPAX)
  • Output: XML/JSON response object containing the list of entries that correspond to values or URIs of BioPAX objects found at the end of the query path.

• top_pathways: Get all "Top" Pathways

  • Parameters:
    • organism - filter by organism (array)
    • datasource - filter by data source (array)
  • Output: XML/JSON object containing the list of root pathways (XML schema is the same as for search query)

• help: Help web service, including -

  • help/commands: List of Webservice Commands
    • help/commands/{cmd}: WS Command Info
  • help/formats: List of Data Formats
    • help/formats/{fmt}: Output Formats Info
  • help/types: List of BioPAX Types
    • help/types/{type}: BioPAX Class Info
  • help/datasources (use 'get' or 'search' instead)
  • help/organisms (use 'get' or 'search' instead)
  • help/directions: List of Directions (graph query parameter)
    • help/directions/{dir}: Direction Info
  • help/types/properties: List of all BioPAX properties (name, domain, ranges)
    • help/types/{type}/properties: List of BioPAX properties of this class
  • help/types/inverse_properties: List of all inverse Paxtools API properties (name, domain, ranges)
    • help/types/{type}/inverse_properties: List of inverse Paxtools API properties of this class
  • Output: XML or JSON - if .json ext. suffix is added (it contains: id, title, member help records, etc.)

Links

• http://awabi.cbio.mskcc.org/pc2/ (demo/test)
• http://purl.org/pc2/test/ (test)
• http://www.pathwaycommons.org/pc2/ (production)