BiVeS – WebService

One of the options to interact with BiVeS is speaking to its Web Service via network.
This allows for an easy integration of BiVeS in non-Java projects.

Usage

The web service expects a JSON stream of the form:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "files":
    {
      "id1": "URI1",
      "id2": "URI2",
      [...]
    },
  "get":
    [
      "xmlDiff",
      "documentType",
      [...]
    ]
}

So, the JSON object contains two entities. On the one hand the key files supplies an associative array of URIs to files indexed by ids and on the other hand the key get defines an array of tasks for BiVeS. We currently implemented the following tasks:

  • documentType: detects the type of each file. returns an arry of strings indicating the type of the document. to date the following return values are possible: “XML”, “CellML”, “SBML” and of course an empty array.
  • meta: reads each file and prints some meta information, such as model id and model name, if available.
  • xmlDiff: detects the differences between two documents and returns the XML patch.
  • crnGraphml: detects the differences and returns the highlighted chemical reaction network encoded in GraphML
  • crnDot: detects the differences and returns the highlighted chemical reaction network encoded in Dot
  • reportHtml: detects the differences and returns the HTML report
  • reportMd: detects the differences and returns the MarkDown report
  • compHierarchyGraphml: detects the differences and returns the highlighted hierarchy graph of all components in a CellML document encoded in GraphML (just available for CellML models)
  • compHierarchyDot: detects the differences and returns the highlighted hierarchy graph of all components in a CellML document encoded in Dot (just available for CellML models)

Please note, all these tasks might return null: for example, not every model contains information about the encoded chemical reaction network. Thus, we may not be able to deliver the the highlighted graph.

The response is then also encoded in JSON. Using curl to send the request

1
2
3
4
5
6
7
8
9
10
11
~dev/bives master » curl -d '{
        "get":
        [
         "documentType", "reportHtml"
        ],
        "files":
        {
          "versionA":"http://budhat.sems.uni-rostock.de/download?downloadModel=25",
          "versionB":"http://budhat.sems.uni-rostock.de/download?downloadModel=25"
        }
     }' bives.sems.uni-rostock.de

the result may look like the following:

1
2
3
4
5
6
7
8
{
   "documentType":
   {
      "versionA": ["XML","SBML"],
      "versionB":["XML","SBML"]
   },
   "reportHtml": "<h1>SBML Differences<\/h1><ul><li>Both documents have same Level\/Version: <strong>L2V4<\/strong><\/li><\/ul>"
}

Since the versionA and versionB are the same file there aren’t any differences, but it gives you an idea of how the output will look like. To learn more about the different formats have a look at the output format descriptions.

More information is available from our BiVeS-WebService trac project. There is also a client library for the web service.

Setup

We installed the webservice at bives.bio.informatik.uni-rostock.de, so you are free to evaluate its capabilities. But we unfortunately only have limited resources and cannot assure a high availablity and a good perfomance. Moreover, our instance will also serve as test server. Thus, the running version might not be stable.
Therefore, we recommend to install your own instance of the web service. All you need is a Java based web server, such as Apache Tomcat. Just deploy our war file to your web server and everything should work out of the box. Do not hesitate to contact us if you need help installing the webservice.

All binaries are available from our bin-repository.