Metadata Rest Endpoints
Common Aspects
Funcionality
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 |
Responses
Server Response
Understanding the server Responses
The server response is divided within 2 main sections they are the header and response.
- "header"
- Contains information about the API
- "response"
- Is the container for the response
- "num_total_results"
- By default, only 10 results are shown.
- This field tells you if there are more results hidden (e.g. if the user asks for all the samples, there might be hundreds or thousands)
- "results"
- The list of objects returned.
HTTP response codes
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 |
| 400 | BAD REQUEST | Request incorrectly formulated |
| 401 | UNAUTHORIZED/FORBIDDEN | You do not have permissions over the object you are trying to access. / The authorized 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. Contact the Heldpesk to notify the issue. |
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/v3/analyses/{id}
https://metadata.ega-archive.org/v3/dacs/{id}
https://metadata.ega-archive.org/v3/datasets/{id}
https://metadata.ega-archive.org/v3/runs/{id}
https://metadata.ega-archive.org/v3/samples/{id}
https://metadata.ega-archive.org/v3/studies/{id}
Worked example for the EGA data access committee(DAC) EGAC00001000514
https://metadata.ega-archive.org/v3/dacs/EGAC00001000514
Points to notice
Please, be advised that all EGA objects can be queried by using the same endpoint (this will return by default 10 results per page). For example:
https://metadata.ega-archive.org/v3/datasets
Returns 10 results.
https://metadata.ega-archive.org/v3/datasets?limit=5&skip=15
Returns 5 results skipping the initial 15 results. Notice that “skip” needs to be multiple of “limit” in order to display new 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/v3/datasets?query_by=dac&query_id=EGAC00001000010
Below, you can find worked examples on how to perform the call to the API.
https://metadata.ega-archive.org/v3/analyses?query_by=dataset&query_id=EGAD00001000645
https://metadata.ega-archive.org/v3/files?query_by=dataset&query_id=EGAD00001000645
https://metadata.ega-archive.org/v3/runs?query_by=dataset&query_id=EGAD00001000620
https://metadata.ega-archive.org/v3/samples?query_by=dataset&query_id=EGAD00001000620
https://metadata.ega-archive.org/v3/datasets?query_by=sample&query_id=EGAN00001092114
https://metadata.ega-archive.org/v3/dacs?skip=0&limit=0&query_by=file&query_id=EGAF00000056146
https://metadata.ega-archive.org/v3/datasets?skip=0&limit=0&query_by=file&query_id=EGAF00000056146
https://metadata.ega-archive.org/v3/studies?skip=0&limit=0&query_by=file&query_id=EGAF00000056146
Points to notice
All objects can be returned from a cross query by adding &limit=0. For example:
https://metadata.ega-archive.org/v3/files?query_by=dataset&query_id=EGAD00001000645&limit=0"
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 | Submission | File |
|---|---|---|---|---|---|---|---|---|---|---|
| Analysis | ✔ | ✔ | ||||||||
| Dac | ✔ | ✔ | ||||||||
| Dataset | ✔ | ✔ | ✔ | ✔ | ||||||
| Experiment | ✔ | ✔ | ✔ | ✔ | ||||||
| Policy | ✔ | |||||||||
| Run | ✔ | ✔ | ✔ | |||||||
| Sample | ✔ | ✔ | ✔ | |||||||
| Study | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ||||
| Submission | ||||||||||
| File | ✔ |