Common Aspects
Common Aspects
Functionality
The EGA Submitter Rest API allows submitters to upload or request metada from EGA, such as ANALYSIS, DAC, DATASET, EXPERIMENT, POLICY, RUN, SAMPLE, STUDY and SUBMISSION. The following figure shows the dependencies between objects with arrows (i. e. in runs there is a mandatory reference to experiments, therefore runs depend on experiments) and how they are grouped under a submission .
Input data can be in XML or JSON format. The latter allows you to take advantage of a new funcionality which is represented with the green arrow in the figure and that simplifies the managing of runs, experiments and samples. Using the Json format runs and samples can be linked without having to use experiments to do this. So, instead of having to repeat the same experiment data as many times as runs you have to point to the corresponding samples (first figure below), you can point runs to samples and to a common experiment that will be shared among many runs (second figure below).
In the following sections we detail several basic concepts that are very important to understand the global operation of both the API and the database.
Identifiers
The most important attributes of any EGA object are the identifiers. Each object is identified by four unique codes: INTERNAL_EBI_ID: this is the internal EGA identifier used by the EBI which is shared across EBI’s databases, e.g. ENA INTERNAL_CRG_ID: same purpose as the INTERNAL_EBI_ID but applies only to the CRG instance of the database EGA_ACCESSION_ID: this is the ID displayed everywhere, shared among all EGA locations and specific for each data type (More information on the list below) ALIAS: unique name of each object defined by the user. NOTE: It is unique per user and object.
| 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 |
Submission and object status
EGA submitted objects might pass through different statuses. When a new object is created its status is always DRAFT. This status provides complete freedom to the user since the only thing that is set is the INTERNAL_CRG_ID whereas the rest of the attributes can be blank. The object can also be deleted or edited with no concern.
An object can be validated at any time, leading to two different scenarios: VALIDATED and VALIDATED_WITH_ERRORS. The first, validated, indicates that all mandatory attributes have been provided and are valid and also that references to other objects are correct, whereas the second, returns a list of errors that need to be fixed. Each scenario is a status by itself and the object can be edited, returning it to the DRAFT status.
From any status an object can be SUBMITTED. This pushes the object through a more exhaustive validation (e.g. references to files are verified) and if successful, generates a new identifier, the EGA_ACCESSION_ID, which will be unique and never re-used, and makes the object visible at all EGA locations.
There is an special status called PARTIALLY_SUBMITTED which only applies to submissions and experiments. In the first case, it means that some objects (but not all) that belong to this submission have already been submitted. In the second one, it means that this experiment has been submitted but there are still some not submitted runs that point to it (see second figure in Functionality).
The figu re below depicts the workflow we have just described.
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 he/she created, there might be hundreds or thousands)
- "resultType"
- The type of the objects returned (e.g. sample, DAC, datasets, etc.).
- "result"
- The list of objects returned.
- From "id" to "xmlRootElement" are common fields shared among all objects.
- "status"
- Valid values: DRAFT , VALIDATED, VALIDATED_WITH_ERRORS , PARTIALLY_SUBMITTED (only for submissions and experiments) and SUBMITTED .
- "validationResult"
- TRUE if the object passes the validation; otherwise FALSE.
- By default its value is FALSE. User must validate or submit the object to get this value updated with the result of the validation.
- NOTE: When submitting, the process automatically validates the object.
- Users must look at this field to know if the object has passed the validation .
- If it doesn't, user must look in "validationErrorMessages" or "submissionErrorMessages" to know what is wrong.
- "egaAccessionId"
- It is automatically set after the object has been successfully submitted.
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. |
