1. BioModels Avatar BioModels
  2. BBR2015
  3. jummp-biomodels

Wiki

Clone wiki

jummp-biomodels / Web Services

View History

The repository can be accessed programmatically through a set of web-services exposing model retrieval, search and browse functionalities.

Format

The general structure of the web-service is a URL of the form /servicename?format=X where X may be xml or json, which determines the language of the response.

Model related Web Services

It is possible to access information related to a model and download the model file using web-services. The caveat here is that the user must have access rights to the model. Currently, we do not support authenticated web-services, therefore the requests must be made for public models, or from a browser where the user is already logged into the website and is querying private models.

The services take as argument a model identifier. The model identifier is a composite of the model id and optionally, the revision id, under the format: model-id.revision-id. The revision-id is relative to the model. If the revision id is omitted, then the latest revision of the model accessible to the user is retrieved. For example, identifier MODEL0003.2 refers to revision 2 of model MODEL0003, while identifier MODEL0003 refers to the latest version of model MODEL0003 available to the user.

Model Information

URL: /model-identifier

The model web service returns information closely corresponding to the first three tabs of the generic model display. An example output (with the format specified as XML) is shown below.

Result for /model/model-identifier?format=xml

#!xml
<?xml version="1.0"?>
<model>
  <identifier>MODEL1108260012</identifier>
  <name>Beltrami1995_ThrombinGeneration_D</name>
  <description>
    <notes xmlns="http://www.sbml.org/sbml/level2/version4">
      <body xmlns="http://www.w3.org/1999/xhtml">
        <p>This model originates from BioModels Database: A Database of Annotated Published Models (http://www.ebi.ac.uk/biomodels/). It is copyright (c) 2005-2011 The BioModels.net Team. <br/> For more information see the <a href="http://www.ebi.ac.uk/biomodels/legal.html" target="_blank">terms of use</a> . <br/> To cite BioModels Database, please use: <a href="http://www.ncbi.nlm.nih.gov/pubmed/20587024" target="_blank">Li C, Donizelli M, Rodriguez N, Dharuri H, Endler L, Chelliah V, Li L, He E, Henry A, Stefan MI, Snoep JL, Hucka M, Le Nov&#xE8;re N, Laibe C (2010) BioModels Database: An enhanced, curated and annotated resource for published quantitative kinetic models. BMC Syst Biol., 4:92.</a> </p>
      </body>
    </notes>
  </description>
  <firstPublished>2011-06-14 11:56:31.0 BST</firstPublished>
  <publication>http://identifiers.org/pubmed/7568009</publication>
  <format>
    <name>SBML</name>
    <version>L2V4</version>
  </format>
  <files>
    <additional>
      <additionalFile>
        <description>Auto-generated XPP file</description>
        <fileSize>2064</fileSize>
        <name>BIOMD0000000369.xpp</name>
      </additionalFile>
      <additionalFile>
        <description>Auto-generated PDF file</description>
        <fileSize>137347</fileSize>
        <name>BIOMD0000000369.pdf</name>
      </additionalFile>
      <additionalFile>
        <description>Auto-generated SBML file with URNs</description>
        <fileSize>9711</fileSize>
        <name>BIOMD0000000369_urn.xml</name>
      </additionalFile>
    </additional>
    <main>
      <modelFile>
        <fileSize>9297</fileSize>
        <name>BIOMD0000000369_url.xml</name>
      </modelFile>
    </main>
  </files>
  <history>
    <revisions>
      <revision>
        <comment>Original import of Jesty1995_ThrombinGeneration_D</comment>
        <submitted>1314377402000</submitted>
        <submitter>Michael Schubert</submitter>
        <version>1</version>
      </revision>
      <revision>
        <comment>
Current version of Beltrami1995_ThrombinGeneration_D
</comment>
        <submitted>1334952192000</submitted>
        <submitter>Michael Schubert</submitter>
        <version>2</version>
      </revision>
    </revisions>
  </history>
</model>

The data returned by the service provides information about the model, files associated with the model and revision history. Model information includes name, description, publication link and model format. The file element consists of sub-elements for main and additional files. The history element consists of a list of revisions, each with the comment, version number (relative to the model) and submission and last modification time. The times are specified in unix time in milliseconds.

Model File Information

URL: /model/files/model-identifier

The files web service returns information returned by the model web service, but restricted to the files element. An example output (with a format specified as XML) is shown below.

Result for /model/files/model-identifier?format=xml

#!xml
<?xml version="1.0"?>
<modelFiles>
  <additional>
    <additionalFile>
      <description>Auto-generated SBML file with URNs</description>
      <fileSize>9711</fileSize>
      <name>BIOMD0000000369_urn.xml</name>
    </additionalFile>
    <additionalFile>
      <description>Auto-generated PDF file</description>
      <fileSize>137347</fileSize>
      <name>BIOMD0000000369.pdf</name>
    </additionalFile>
    <additionalFile>
      <description>Auto-generated XPP file</description>
      <fileSize>2064</fileSize>
      <name>BIOMD0000000369.xpp</name>
    </additionalFile>
  </additional>
  <main>
    <modelFile>
      <fileSize>9297</fileSize>
      <name>BIOMD0000000369_url.xml</name>
    </modelFile>
  </main>
</modelFiles>

The data about files include the file name, the size of the file, and (for additional files) the description provided by users when submitted the files.

Model File Download

URL: /model/download/model-identifier?filename=file-name

The model files can be downloaded with the model download service. The filename parameter is optional, and if omitted the combine archive of the model named under the pattern modelidentifier-yyyyMMdd-hhmmss.omex is downloaded.

Browsing and Searching Models related Web Services

Model summaries can be retrieved using two related web-services:

  1. /models can be used for browsing the models which a logged in user can access.
  2. /search can be used for searching interested models hosting in the repository.

Both services share a number of parameters related to sorting and pagination, which are described below. In addition to the common parameters, the search service expects a parameter query, which is the search string.

Common Parameters

The following optional parameters can be included in the search services:

sort - The indicator to sort by. Can be one of the following: relevance, name-asc, name-desc, id-asc, id-desc, author-asc, author-desc, publication_year-asc and publication_year-desc. The direction of sorting is either 'asc' (for ascending), or 'desc' (for descending).

offset - The offset to begin returning results from. The services return a maximum of 10 results for scalability, therefore this parameter can be used for pagination or retrieving additional results.

Results

The structure of results returned by browse and search is similar, and consists of an element describing the search parameters in the query and a list of model summary elements. Each model summary element consists of: name, id, format, submission date, last modified and URL (in the model repository).

Additionally, the browse service returns a modelsAvailable element, specifying the number of models available for access through the web service, while the search service returns a matches element, specifying the number of models that match the search query. This can aid in the pagination. Finally, there is a request parameters element specifying the query parameters used in the request.

Result for /models?format=json&sort=name-asc&offset=12

#!json
{
  "model": [
    {
      "format": "SBML",
      "id": "MODEL9147091146",
      "lastModified": "2008-03-13T11:42:57Z",
      "name": "Ajay_Bhalla_2007_Bistable",
      "submissionDate": "2011-04-05T15:23:23Z",
      "submitter": "Sharat Vayttaden",
      "url": "http://127.0.0.1:8080/jummp-biomodels/model/MODEL9147091146"
    },
    {
      "format": "SBML",
      "id": "MODEL9147232940",
      "lastModified": "2011-04-05T15:22:40Z",
      "name": "Ajay_Bhalla_2007_PKM",
      "submissionDate": "2008-03-13T11:42:44Z",
      "submitter": "Sharat Vayttaden",
      "url": "http://127.0.0.1:8080/jummp-biomodels/model/MODEL9147232940"
    },
    {
      "format": "SBML",
      "id": "BIOMD0000000295",
      "lastModified": "2008-12-03T12:40:08Z",
      "name": "Akman2008_Circadian_Clock_Model1",
      "submissionDate": "2015-02-25T13:50:18Z",
      "submitter": "Lukas Endler",
      "url": "http://127.0.0.1.96:8080/jummp-biomodels/model/BIOMD0000000295"
    }
  ],
  "modelsAvailable": 123,
  "queryParameters": {
    "maxResults": 10,
    "offset": 12,
    "sortBy": "name",
    "sortDirection": "asc"
  }
}
The example above shows the results in json format for a browse query. The offset is specified as 12, and there are 123 models available from the repository, resulting in three models being retrieved.

Results for search?query=MAPK+cascade&offset=10&numResults=10&sort=id-asc&format=json

#!json
{
  "matches": 86,
  "models": [
    {
      "format": "SBML",
      "id": "BIOMD0000000031",
      "lastModified": "2012-01-15T00:05:00Z",
      "name": "Markevich2004_MAPK_orderedMM2kinases",
      "submissionDate": "2005-01-13T00:09:00Z",
      "submitter": "Nicolas Le Novère",
      "url": "http://127.0.0.1:8080/jummp-biomodels/model/BIOMD0000000031"
    },
    {
      "format": "SBML",
      "id": "BIOMD0000000032",
      "lastModified": "2016-01-08T00:04:00Z",
      "name": "Kofahl2004_PheromonePathway",
      "submissionDate": "2005-01-13T00:09:00Z",
      "submitter": "Harish Dharuri",
      "url": "http://127.0.0.1:8080/jummp-biomodels/model/BIOMD0000000032"
    },
    {
      "format": "SBML",
      "id": "BIOMD0000000049",
      "lastModified": "2014-01-04T00:04:00Z",
      "name": "Sasagawa2005_MAPK",
      "submissionDate": "2006-01-12T00:01:00Z",
      "submitter": "Shinya Kuroda",
      "url": "http://127.0.0.1:8080/jummp-biomodels/model/BIOMD0000000049"
    },
    {
      "format": "SBML",
      "id": "BIOMD0000000084",
      "lastModified": "2012-01-14T00:05:00Z",
      "name": "Hornberg2005_ERKcascade",
      "submissionDate": "2012-01-14T00:05:00Z",
      "submitter": "Nicolas Le Novère",
      "url": "http://127.0.0.1:8080/jummp-biomodels/model/BIOMD0000000084"
    },
    {
      "format": "SBML",
      "id": "BIOMD0000000146",
      "lastModified": "2014-01-27T00:05:00Z",
      "name": "Hatakeyama2003_MAPK",
      "submissionDate": "2014-01-27T00:05:00Z",
      "submitter": "Enuo He",
      "url": "http://127.0.0.1:8080/jummp-biomodels/model/BIOMD0000000146"
    }
  ],
  "queryParameters": {
    "maxResults": 10,
    "offset": 10,
    "sortBy": "id",
    "sortDirection": "asc"
  }
}
This example illustrates the results in JSON format for a search hit via search web services. The offset is specified as 10, and there are 86 models matching with the being query string from the repository, resulting in five models being retrieved.

Updated