How to use the API

How to use the API

In the following sections we detail how to use this API both for metadata retrieval and submission. The examples we provide here use the curl command to perform all the actions, but they can be easily adapted to be used on your preferred scripting language (e.g. Python) or in REST clients (e.g. Postman).

Login and Logout

How to obtain a session ID

An active session is required to work with the API. Each time you log in with your credentials a new session is started, which is identified by an X-Token. Below an example on how to obtain one using curl:

All responses of the API are in JSON format. If successful, the response should include a new Token to use during the session:

  "session" : {
        "sessionToken" : "12c810d5-0974-4d11-937f-bd75a81de762",
        "expeditionTime" : 1429107047601,
        "expirationTime" : 1429110647601,
        "method" : "N/A",
        "ipAddress" : "192.168.110.14"
      }

Points to notice:

How to log out

Simply use the following endpoint:

Retrieving metadata

The calls to the metadata service are basically identical for all EGA objects as well as the filters and methods available. Importantly, EGA objects can fall under a submission project. This concept is not very important when retrieving data, as it only provides another way to filter the results, however, it has a key role when submitting new objects. We will deal with this later on.

The following objects can be queried by the catalog, which correspond to the name of the method:

• analyses
• dacs
• datasets
• experiments
• policies
• runs
• samples
• studies
• submissions

Filtering by status: Status can be filtered by appending '?status=[name of the status]' at the end (see Enumerations for the complete list of values).

For submitted objects (registered in Webin or XML Programmatically), it is necessary to append ?status=SUBMITTED When no status is provided, an aggregation of DRAFT, VALIDATED, VALIDATED_WITH_ERRORS, PARTIALLY_SUBMITTED is returned (that is, all except SUBMITTED). Therefore, only metadata objects registered via the REST API and not submitted yet are retrieved.

Below some examples:

Display all studies on draft, validated and validated with errors:

Display all studies that have been validated and had errors:

Show all samples that have been submitted:

All calls return a list of JSON objects, one for each EGA object, that contains all attributes of the object.

Filtering the Results

The identifiers described in section Identifiers can be used to filter out the results for a given object. If no parameter is specified, the filtering is done by either of the two internal IDs indistinctly:

Notice that “{sampleId}” must be an identifier of an already existent sample (in this example). To filter by EGA accession Id or alias, ‘?idType=[name of the id]’ must be added at the end. Example:

Filtering by submission

You can list any objects filtering by submission Id.

All analyses that belong to this submission:

All experiments that belong to this submission:

As when retrieving metadata, you can add '?status=[name of the status]' at the end to also filter by status. All analyses from this submission that are submitted:

Remember that if no status is provided, an aggregation of DRAFT, VALIDATED, VALIDATED_WITH_ERRORS, PARTIALLY_SUBMITTED is returned (that is, all except SUBMITTED).

Retrieving information about files

Apart from metadata objects the API also provides a way to obtain information about the uploaded files. This may come from different sources, which must be specified in the call: CRG_INBOX : Files uploaded to CRG's box which have not been archived yet. EBI_INBOX: files that the user has uploaded to their box at EBI that have not been archived yet. A process runs every X hours and copies all files uploaded to CRG boxes to EBI boxes. So, all files that are seen using CRG_INBOX are also seen using EBI_INBOX (be aware of the delay).

Example:

Output formatting

Additional data like parameters for pagination (offset and limit) can be added to all data retrieval queries in order to format the output. They must be specified as query parameters (i. e. offset=1&limit=5).

Enumerations

Enumerations contain list of terms that are used as available options at different points of the API. They are all available under the /enums path and are public, so you don't need to be authenticated to call them. Some of them refer to the metadata whereas other provide parameters for calls or methods:

APi details

/path/enums/actions: Action values. EDIT/VALIDATE/SUBMIT.
/path/enums/actions/submission_statuses: Submission status values.
/path/enums/actions/id_types: List of the different ids accepted at the EGA.
/path/enums/actions/entity_statuses: Object status values.

Metadata

/path/enums/analysis_file_types: Analysis file type accepted values.
/path/enums/analysis_types: EGA elegible analysis types.
/path/enums/case_control: Case/control accepted values.
/path/enums/dataset_types: Dataset type accepted values.
/path/enums/experiment_types: Experiment types.
/path/enums/file_types: Run file type accepted values.
/path/enums/genders: Gender accepted values.
/path/enums/instrument_models: Platform accepted values
/path/enums/library_selections: Library Selection accepted values.
/path/enums/library_sources: Library source accepted values.
/path/enums/library_strategies: Library Strategy accepted values.
/path/enums/reference_chromosomes: Chromosome values.
/path/enums/reference_genomes: Genome values.
/path/enums/study_types: Study type accepted values.

For instance, this call lists all the experiment types available when registering a new experiment object:

"response" : {
    "numTotalResults" : 5,
    "resultType" : "eu.crg.ega.microservice.dto.submitter.AttributeData",
    "result" : [ {
      "tag" : "4",
      "value" : "Curation",
      "label" : null,
      "unit" : null
    }, {
      "tag" : "1",
      "value" : "Exome sequencing",
      "label" : null,
      "unit" : null
    }, {
      "tag" : "2",
      "value" : "Genotyping by array",
      "label" : null,
      "unit" : null
    }, {
      "tag" : "0",
      "value" : "Whole genome sequencing",
      "label" : null,
      "unit" : null
    }, {
      "tag" : "3",
      "value" : "transcriptomics",
      "label" : null,
      "unit" : null
    } ]
  }