Metadata Rest Endpoints
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.ega-archive.org/analyses/{id}
https://metadata.ega-archive.org/dacs/{id}
https://metadata.ega-archive.org/datasets/{id}
https://metadata.ega-archive.org/runs/{id}
https://metadata.ega-archive.org/samples/{id}
https://metadata.ega-archive.org/studies/{id}
Worked example for the EGA data access committee(DAC) EGAC00001000514
https://metadata.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.ega-archive.org/datasets
Returns all the datasets registered at the EGA.
https://metadata.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.ega-archive.org/dacs/EGAC00001000010/datasets
Below, you can find worked examples on how to perform the call to the API.
https://metadata.ega-archive.org/datasets/EGAD00001000645/analyses
https://metadata.ega-archive.org/datasetsEGAD00001000645/files
https://metadata.ega-archive.org/datasets/EGAD00001000620/runs
https://metadata.ega-archive.org/datasets/EGAD00001000620/samples
https://metadata.ega-archive.org/samples/EGAN00001092114/datasets
https://metadata.ega-archive.org/files/EGAF00000056146/dacs
https://metadata.ega-archive.org/files/EGAF00000056146/datasets
https://metadata.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