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.
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
- http://www.omicsdi.org/ws/dataset/search?query=human&start=0&size=50
- http://www.omicsdi.org/ws/dataset/search?query=human&start=0&size=20
Sort
The result datasets can be sorted using the title, description, publication date, accession id and the relevance of the query term..
Examples
- http://www.omicsdi.org/ws/dataset/search?query=human&sort_field=id
- http://www.omicsdi.org/ws/dataset/search?query=human&sort_field=publication_date
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
- http://www.omicsdi.org/ws/dataset/search?query=human
- http://www.omicsdi.org/ws/dataset/search?query=cancer
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
- http://www.omicsdi.org/ws/dataset/search?query=human AND omics_type:"Proteomics"
- http://www.omicsdi.org/ws/dataset/search?query=human AND omics_type:"Metabolomics"
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
- http://www.omicsdi.org/ws/dataset/search?query=human AND repository:"MassIVE"
- http://www.omicsdi.org/ws/dataset/search?query=human AND repository:"Metabolights"
- http://www.omicsdi.org/ws/dataset/search?query=human AND repository:"PeptideAtlas"
- http://www.omicsdi.org/ws/dataset/search?query=human AND repository:"PRIDE"
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
- http://www.omicsdi.org/ws/dataset/search?query=human AND TAXONOMY:"9606"
- http://www.omicsdi.org/ws/dataset/search?query=human AND TAXONOMY:"10090"
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
- http://www.omicsdi.org/ws/dataset/search?query=human AND tissue:"Brain"
- http://www.omicsdi.org/ws/dataset/search?query=human AND tissue:"Cell culture"
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
- http://www.omicsdi.org/ws/dataset/search?query=human AND tissue:"Breast cancer"
- http://www.omicsdi.org/ws/dataset/search?query=human AND tissue:"Lymphoma"
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
- http://www.omicsdi.org/ws/dataset/search?query=human AND modification:"iodoacetamide derivatized residue"
- http://www.omicsdi.org/ws/dataset/search?query=human AND modification:"monohydroxylated residue"
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
- http://www.omicsdi.org/ws/dataset/search?query=human AND instrument_platform:"LTQ"
- http://www.omicsdi.org/ws/dataset/search?query=human AND instrument_platform:"Q Exactive"
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
- http://www.omicsdi.org/ws/dataset/search?query=human AND publication_date:"2015"
- http://www.omicsdi.org/ws/dataset/search?query=human AND publication_date:"2014"
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
- http://www.omicsdi.org/ws/dataset/search?query=human AND technology_type:"Mass Spectrometry"
- http://www.omicsdi.org/ws/dataset/search?query=human AND technology_type:"Shotgun proteomics"
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.