API overview

Most data in the Datatsets Discovery Index can be accessed programmatically using a RESTful API allowing for integration with other resources. The API implementation is based on the Spring Rest Framework.

Web browsable API

The OmicsDI API is web browsable, which means that:

  • The query results returned by the API are available in JSONformat. This ensures that they can be viewed by human and accessed programmatically by computer.

  • The main RESTful API page provides a simple web-based user interface, which allows developers to familiarise themselves with the API and get a better sense of the OmicsDI data before writing a single line of code.

  • many resources are hyperlinked so that it's possible to navigate the API in the browser.

As a result, developers can familiarise themselves with the API and get a better sense of the OmicsDI data.

Browse the API

Versioning

To ensure that changes in the OmicsDI API don't break the applications relying on it, the API is versioned, and the version is included in the API's URL.

For example, the current API is at Version 1 and is available at http://www.omicsdi.org/ws/, and the next version will be available at http://www.omicsdi.org/ws/.

The latest version of the API can be accessed at http://www.omicsdi.org/ws/, but it's not recommended to use this endpoint for long-term development as the underlying data model may change.

No backward-incompatible changes are made to a version after it has been made public. More specifically, it's guaranteed that within one version there will be no:

  • changing urls
  • deleting or renaming data fields
  • changing data field types

The following non-disruptive changes may be implemented to a public API:

  • adding new endpoints
  • adding new data fields
  • adding new filtering methods

An advance notice will be given before obsoleting an API version. To stay up to date, please consider signing up for the PRIDE Twitter account.


API documentation

Example responses

Responses containing multiple entries have the following fields:

  • count is the number of entries in the matching set.
  • datasets is an array of datasets.
  • facets is an array of facets.

Example


    first code fragment

Responses containing just a single dataset have some extra navigation fields, and without the facets


    second code fragment

Pagination

Responses containing multiple datasets are paginated to prevent accidental downloads of large amounts of data and to speed up the API.

The page size is controlled by the size parameter. Its default value is 20 datasets per page, and the maximum number of datasets per page is 100.

Another parameter is start which indicates the numeric order (starting from 0, not 1) of the first dataset in this page. Its default value is 0.

Examples

Sort

The result datasets can be sorted using the title, description, publication date, accession id and the relevance of the query term..

Examples

Output formats

The following output format is: JSON

Filtering

The API supports several filtering operations that complement the main OmicsDI search functionality.

Filtering by search term

There is 1 url parameter: query

Examples

Filtering by omics type

The omics type can be specified by adding terms in the query url parameter with key: omics_type (possible values: Proteomics, Metabolomics,Genomics, Transcriptomics).

Examples

Filtering by database

The database can be specified by adding terms in the query url parameter with key: repository (possible values:MassIVE, Metabolights, PeptideAtlas, PRIDE, EGA, Metabolights, Metabolomics Workbench, MetabolomeExpress, GNPS, ArrayExpress, ExpressionAtlas).

Examples

Filtering by Organism

The organism can be specified by adding terms in the query url parameter with key: TAXONOMY (possible values must be the TAXONOMY id: 9606, 10090...).

Examples

Filtering by Tissue

The tissue can be specified by adding terms in the query url parameter with key: tissue (possible values: Liver, Cell culture, Brain, Lung...).

Examples

Filtering by Disease

The disease can be specified by adding terms in the query url parameter with key: disease (possible values: Breast cancer, Lymphoma, Carcinoma, prostate adenocarcinoma...).

Examples

Filtering by Modification (in proteomics)

The Modifications (in proteomics) can be specified by adding terms in the query url parameter with key: disease (possible values: Deamidated residue, Deamidated, Monohydroxylated residue, Iodoacetamide derivatized residue...).

Examples

Filtering by Instruments & Platforms

The Instruments & Platforms can be specified by adding terms in the query url parameter with key: instrument_platform (possible values: QSTAR, LTQ Orbitrap, Q Exactive, LTQ...).

Examples

Filtering by Publication Date

The Publication Date can be specified by adding terms in the query url parameter with key: "publication_date" (possible values: 2015, 2014, 2013, 2014...).

Examples

Filtering by Technology Type

The Technology Type can be specified by adding terms in the query url parameter with key: "technology_type" (possible values: Mass Spectrometry, Bottom-up proteomics, Gel-based experiment, Shotgun proteomics...).

Examples

Combined filters

Any filters can be combined to narrow down the query using the AND operator. More logical operators will be supported in the future.

Examples