Need Help?

Metadata Rest Endpoints

Common Aspects

Functionality

Identifiers

Requests and Responses

Request

Response

Querying

Querying by Object

Cross-Querying by Object

Common Aspects

Functionality

The Metadata REST API allows EGA users to request metadata from the EGA.
Using this api you will be able to obtain the publicly available information from EGA study, sample, experiment, run, analysis, policy, dac and dataset. The API also allows for objects to be cross-referenced in order to obtain for example all the datasets linked to a dac.

Identifiers

EGA objects can be identified by their unique accession. These are ID's displayed everywhere, shared among all EGA locations and specific for each data type (More information on the list below)

EGA Accession ID EGA Object description
EGAS EGA Study Accession ID
EGAC EGA DAC Accession ID
EGAP EGA Policy Accession ID
EGAN EGA Sample Accession ID
EGAR EGA Run Accession ID
EGAX EGA Experiment ID
EGAZ EGA Analysis Accession ID
EGAD EGA Dataset Accession ID
EGAB EGA Submission ID
EGAF EGA File Unique Accession ID

Server Request and Response

Request

All the endpoints implement these two HTTP methods, GET and HEAD.

Moreover, there is an authentication layer that allows to disclose the private information about each object if the user runs the endpoint with their token and has permissions to the related dataset.

HTTP Method Description
GET Returns the objects and their public information (including private information if the user has permissions)
HEAD Returns the count of objects to be returned

Response

API responses are diverse but they always return a status call. Below you have a summary on what these codes mean and some tips that can help you troubleshooting them:

HTTP Status Code Description Resolution
200 OK No error handling necessary
206 Partial Content Expected status code when paginating the results. No error handling necessary
400 BAD REQUEST Request incorrectly formulated
401 UNAUTHORISED/FORBIDDEN You do not have permissions over the object you are trying to access. / The authorised user is not permitted to make the given request.
404 NOT FOUND The object/resource you are trying to access does not exist.
500 INTERNAL SERVER ERROR This is a server-side error, try later. If the issue persists, contact the Heldpesk.

Querying

Querying by Object

In the below documentation, worked examples can be found on how to use the API, to query about each unique EGA object.

https://metadata.test.ega-archive.org/analyses/{id} https://metadata.test.ega-archive.org/dacs/{id} https://metadata.test.ega-archive.org/datasets/{id} https://metadata.test.ega-archive.org/runs/{id} https://metadata.test.ega-archive.org/samples/{id} https://metadata.test.ega-archive.org/studies/{id}

Worked example for the EGA data access committee(DAC) EGAC00001000514

https://metadata.test.ega-archive.org/dacs/EGAC00001000514

Points to notice

Please, be advised that all EGA objects can be queried by using the same endpoint. For example:

https://metadata.test.ega-archive.org/datasets

Returns all the datasets registered at the EGA.

https://metadata.test.ega-archive.org/datasets?limit=5&offset=15

Returns 5 results skipping the initial 15 results.

Cross-Querying by Object

The EGA REST API Metadata also allows for the crossquerying of public metadata.

For example, should I want to query the datasets included in the ICGC DAC:

https://metadata.test.ega-archive.org/dacs/EGAC00001000010/datasets

Below, you can find worked examples on how to perform the call to the API.

https://metadata.test.ega-archive.org/datasets/EGAD00001000645/analyses https://metadata.test.ega-archive.org/datasetsEGAD00001000645/files https://metadata.test.ega-archive.org/datasets/EGAD00001000620/runs https://metadata.test.ega-archive.org/datasets/EGAD00001000620/samples https://metadata.test.ega-archive.org/samples/EGAN00001092114/datasets https://metadata.test.ega-archive.org/files/EGAF00000056146/dacs https://metadata.test.ega-archive.org/files/EGAF00000056146/datasets https://metadata.test.ega-archive.org/files/EGAF00000056146/studies

There are more endpoints included in this category. Please, find all the possibilities (green tick) in the table below.

Table

The table displays in a ordered fashion the objects that can be crossreferenced using the metadata API.

BY Analysis Dac Dataset Experiment Policy Run Sample Study File
Analysis
Dac
Dataset
Experiment
Policy
Run
Sample ✔*
Study ✔*
File

*: These cross queries do not include data from Array-File submissions.

Check out the SPEC