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 3.2 refers to revision 2 of model 3, while identifier 3 refers to the latest version of model 3 available to the user.

Model Information

URL: /model/model-identifier

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

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

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 format specified as XML is shown below)

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

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

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 main file of the model is downloaded.

Browsing and Searching Models

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

1. /models can be used for browsing the models
2. /search can be used for searching the model 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 parameters can be included in the search/browse services:

sortBy - The model attribute to sort by. Can be one of the following: name, format, submitter, submitted and modified.

sortDir - The direction of sorting. Can be '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

Each of these parameters is optional.

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 webservice, 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. The example below shows the results for a browse query. The offset is specified as 12, and there are 14 models available from the repository, resulting in two models being retrieved.

Result for /models?format=xml&sortBy=submitted&sortDir=asc&offset=12