Metadata Rest Endpoints

Functionality

Identifiers

Server responses

HTTP responses codes

Querying by Object

Cross-Querying by Object


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 HTTP connection
    • "code"
      • Please see more about response codes on the table below
  • "response"
    • Is the container for the response
    • "numTotalResults"
      • 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)
    • "resultType"
      • The type of the objects returned (e.g. sample, dac, dataset, etc.).
    • "result"
      • 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://ega-archive.org/metadata/v2/analyses/{id}
 https://ega-archive.org/metadata/v2/dacs/{id}
 https://ega-archive.org/metadata/v2/datasets/{id}?idType=EGA_STABLE_ID
 https://ega-archive.org/metadata/v2/runs/{id}
 https://ega-archive.org/metadata/v2/samples/{id}
 https://ega-archive.org/metadata/v2/studies/{id}

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

 https://ega-archive.org/metadata/v2/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://ega-archive.org/metadata/v2/datasets

Returns 10 results. 

 https://ega-archive.org/metadata/v2/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://ega-archive.org/metadata/v2/datasets?queryBy=dac&queryId=EGAC00001000010
Below, you can find worked examples on how to perform the call to the API. 

 https://ega-archive.org/metadata/v2/analyses?queryBy=dataset&queryId=EGAD00001000645 
 https://ega-archive.org/metadata/v2/files?queryBy=dataset&queryId=EGAD00001000645  
 https://ega-archive.org/metadata/v2/runs?queryBy=dataset&queryId=EGAD00001000620  
 https://ega-archive.org/metadata/v2/samples?queryBy=dataset&queryId=EGAD00001000620  
 https://ega-archive.org/metadata/v2/datasets?queryBy=sample&queryId=EGAN00001092114  
 https://ega-archive.org/metadata/v2/dacs?skip=0&limit=0&queryby=file&queryid=EGAF00000056146 
 https://ega-archive.org/metadata/v2/datasets?skip=0&limit=0&queryby=file&queryid=EGAF00000056146 
 https://ega-archive.org/metadata/v2/studies?skip=0&limit=0&queryby=file&queryid=EGAF00000056146

Points to notice

All objects can be returned from a cross query by adding &limit=0. For example: 

 https://ega-archive.org/metadata/v2/files?queryBy=dataset&queryId=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.

  TO   Analysis   Dac   Dataset   Experiment   Policy   Run   Sample   Study   Submission   File
 Analysis ✔ ✔
 Dac ✔ ✔
 Dataset ✔ ✔ ✔ ✔
 Experiment ✔ ✔ ✔
 Policy ✔
 Run ✔ ✔ ✔
 Sample ✔ ✔
 Study ✔ ✔ ✔ ✔ ✔ ✔
 Submission
 File ✔