Using COPO API

The COPO API is a RESTful website service that allows users to interact with the COPO system. The API is built using the Django REST [1] Framework.

Hint

The button, , indicates that the API method endpoints will produce results from the website host server i.e. if the live COPO website is used to query the endpoint, then, the live results will be retrieved while the opposite occurs if one uses the demo website to query the API method endpoints.

API End-points

The COPO API [2] comprises manifest, sample, statistics and profile endpoints. Their results are available for download in csv, json or ro-crate [3] file formats depending on the record type as shown in the table below.

Each endpoint results contain metadata provided by the submitter.

Available Result Formats for Records
File Format	Available Record Types
csv	Study, Sample, Manifest
json	Study, Sample, Manifest
ro-crate	Sample

Note

The live COPO website API endpoints are used in the examples below.

To use the demo website API endpoints, replace https://copo-project.org/api/ with https://demo.copo-project.org/api/ in the examples below.

Audit Endpoints

Fetch Sample Updates Between Dates

https://copo-project.org/api/audit/sample/{from}/{to}

OR

$ curl -X GET "https://copo-project.org/api/audit/sample/{from}/{to}" -H  "accept: application/json"

This results in a list of sample updates that occurred between a given date period.

Fetch Sample Updates by Manifest ID

https://copo-project.org/api/audit/sample/manifest_id/{manifest_id}

OR

$ curl -X GET "https://copo-project.org/api/audit/sample/manifest_id/{manifest_id}" -H  "accept: application/json"

This results in a list of sample updates by manifest IDs [4].

Fetch Sample Updates by COPO ID

https://copo-project.org/api/audit/sample/{copo_id}

OR

$ curl -X GET "https://copo-project.org/api/audit/sample/copo_id/{copo_id}" -H  "accept: application/json"

This results in a list of sample updates based on {copo_id}.

Fetch Sample Updates by Update Type

https://copo-project.org/api/audit/sample/update_type/{update_type}

OR

$ curl -X GET "https://copo-project.org/api/audit/sample/update_type/{update_type}" -H  "accept: application/json"

This results in a list of sample updates based who performed the update. The update_type can be system or user.

A system update occurs when the update was performed by COPO while a user update occurs when a user reuploads a manifest with amended sample metadata.

Please note that not all sample information that has been uploaded already can be updated when the manifest is reuploaded. Only fields that are updatable are updated when a manifest is reuploaded.

See the Updating Samples section for more information as well as the Fetch updatable fields by project API method.

Fetch Sample Updates by Field and Field Value

https://copo-project.org/api/audit/sample/{field}/{field_value}

OR

$ curl -X GET "https://copo-project.org/api/audit/sample/{field}/{field_value}" -H  "accept: application/json"

This results in a list of sample updates based on a sample field value and one of the following sample fields:

RACK_OR_PLATE_ID
SPECIMEN_ID
TUBE_OR_WELL_ID
biosampleAccession
public_name
sraAccession

Fetch Sample Updates by ASG Sample Type

https://copo-project.org/api/audit/sample/asg

OR

$ curl -X GET "https://copo-project.org/api/audit/sample/asg" -H  "accept: application/json"

This results in a list of updates for ASG [8]. sample types.

Fetch Sample Updates by DTOL Sample Type

https://copo-project.org/api/audit/sample/dtol

OR

$ curl -X GET "https://copo-project.org/api/audit/sample/dtol" -H  "accept: application/json"

This results in a list of updates for DToL [9]. sample types.

Fetch Sample Updates by ERGA Sample Type

https://copo-project.org/api/audit/sample/erga

OR

$ curl -X GET "https://copo-project.org/api/audit/sample/erga" -H  "accept: application/json"

This results in a list of updates for ERGA [10]. sample types.

Manifest Endpoints

Fetch Manifests

https://copo-project.org/api/manifest

OR

$ curl -X GET "https://copo-project.org/api/manifest" -H  "accept: application/json"

This results in a list of all manifest IDs [4]. The manifest identification can be used to retrieve records in the other endpoints.

Fetch Current Manifest Versions

https://copo-project.org/api/manifest/current_version

OR

$ curl -X GET "https://copo-project.org/api/manifest/current_version" -H  "accept: application/json"

This displays the current or latest manifest version of each manifest project brokered through COPO.

Fetch Sample Records by Manifest ID

https://copo-project.org/api/manifest/{manifest_id}

OR

$ curl -X GET "https://copo-project.org/api/manifest/{manifest_id}" -H  "accept: application/json"

This results in a list of sample records for the given manifest IDs [4].

Fetch Manifests between Dates

https://copo-project.org/api/manifest/{from}/{to}

OR

$ curl -X GET "https://copo-project.org/api/manifest/{from}/{to}" -H  "accept: application/json"

This results in a list of all manifest IDs [4] recorded in the given date period.

Fetch Manifests between Dates for a Project

https://copo-project.org/api/manifest/{project}/{from}/{to}

OR

$ curl -X GET "https://copo-project.org/api/manifest/{project}/{from}/{to}" -H  "accept: application/json"

This results in a list of all manifest IDs [4] recorded in the given date period for a given project.

Fetch Sample Record Status in a Manifest

https://copo-project.org/api/manifest/{manifest_id}/sample_statuses

OR

$ curl -X GET "https://copo-project.org/api/manifest/{manifest_id}/sample_statuses" -H  "accept: application/json"

This results in minimal sample status information for each sample contained in the given {manifest_id}.

Validate Manifest by Profile ID

Note

Authentication is required in order to use this API method. Obtain an API token from the following endpoint before using this method:

https://copo-project.org/api/manifest/validate

This results in the ID of the validation report to be queried.

Validate Manifest by Report ID

Note

Authentication is required in order to use this API method. Obtain an API token from the following endpoint before using this method:

https://copo-project.org/api/manifest/validate/report/

OR

$ curl -X POST "https://copo-project.org/api/manifest/validate/report/" -H  "accept: */*" -H  "Content-Type: application/x-www-form-urlencoded" -d "validation_report_id={report-id}

This gives the status and/or validation errors for a manifest based on the manifest report ID.

Validate Manifest

Note

Authentication is required in order to use this API method. Obtain an API token from the following endpoint before using this method:

https://copo-project.org/api/apiKey

https://copo-project.org/api/manifest/validations

OR

$ curl -X POST "https://copo-project.org/api/manifest/validations/" -H  "accept: */*" -d ""

This checks whether a given manifest passes or fails validation for the authorised user.

Sample Endpoints

Fetch Sample Records by Project

https://copo-project.org/api/sample/{project}

OR

$ curl -X GET "https://copo-project.org/api/sample/{project}" -H  "accept: application/json"

This results in a list of all the samples of a project in COPO.

Fetch Sample Records by Associated Project Type

Hint

The associated project type is the project type that the sample is subproject of. For example, a sample may be associated with a project type of “BGE” but the sample itself may be an “ERGA” sample.

In sample records, the associated project type is referred to as associated_tol_project whereas in profile records, it is referred to as associated_type.

https://copo-project.org/api/sample/associated_tol_project/{values}

OR

$ curl -X GET "https://copo-project.org/api/sample/sample/associated_tol_project/{values}" -H  "accept: application/json"

This results in a list of all sample records of a given associated project type(s) in COPO.

Fetch Sample Records between Dates

https://copo-project.org/api/sample/project/manifest_version/fields

OR

$ curl -X GET "https://copo-project.org/api/sample/project/manifest_version/fields}" -H  "accept: application/json"

This results in a list of fields of a project for a given manifest version.

Fetch Sample Records between Dates

https://copo-project.org/api/sample/{from}/{to}

OR

$ curl -X GET "https://copo-project.org/api/sample/{from}/{to}" -H  "accept: application/json"

This results in a list of all samples recorded in the given date period.

Fetch Updatable Fields by Project

https://copo-project.org/api/sample/updatable_fields/{project}

OR

$ curl -X GET "https://copo-project.org/api/sample/updatable_fields/{project}" -H  "accept: */*"

This results in list of fields that can be updated when a manifest is reuploaded/resubmitted in COPO based on the given {project}`.

Fetch Sample Records by COPO ID

Hint

Sample records IDs are referred to as copo_id in COPO and alias in ENA.
Multiple copo_id can be provided as a comma separated list in this endpoint.

https://copo-project.org/api/sample/copo_id/{copo_ids}

OR

$ curl -X GET "https://copo-project.org/api/sample/copo_id/{copo_ids}" -H  "accept: application/json"

This results in full sample information for the sample records returned from the given {copo_ids}.

Fetch Sample Records by Biosample ID

Note

Biosample accession IDs are assigned to sample records by ENA [9] after the samples have been approved by a sample manager [10].
The biosample_id is referred to as biosampleAccession in COPO and biosample_id in ENA.

https://copo-project.org/api/sample/biosample_id/{biosample_ids}

OR

$ curl -X GET "https://copo-project.org/api/sample/biosample_id/{biosample_ids}" -H  "accept: application/json"

This results in full sample information for the sample records returned from the given {biosample_ids}.

Fetch Sample Records by Field and Values

Hint

Multiple values can be provided as a comma separated list in this endpoint.

https://copo-project.org/api/sample/sample_field/{field}/{values}

OR

$ curl -X GET "https://copo-project.org/api/sample/sample_field/{field}/{values}" -H  "accept: application/json"

This results in full sample information for the sample records returned from the given {field}/{values}.

Fetch Study Records by Sample ID

Hint

Multiple sample_ids can be provided as a comma separated list in this endpoint.

https://copo-project.org/api/sample/StudyFromSampleAccession/{sample_ids}

OR

$ curl -X GET "https://copo-project.org/api/sample/StudyFromSampleAccession/{sample_ids}" -H  "accept: application/json"

This results in full sample information for the sample records returned from the given {sample_ids}.

Fetch Sample Records by Study ID

Hint

Multiple biostudyAccessions can be provided as a comma separated list in this endpoint.

https://copo-project.org/api/sample/SampleFromStudyAccession/{biostudyAccessions}

OR

$ curl -X GET "https://copo-project.org/api/sample/SampleFromStudyAccession/{biostudyAccessions}" -H  "accept: application/json"

This results in full sample information for the sample records returned from the given {biostudyAccessions}.

Profile Endpoints

Create Profile Record

Note

Authentication is required in order to use this API method. Obtain an API token from the following endpoint before using this method:

https://copo-project.org/api/apiKey

https://copo-project.org/api/profile//make_profile

OR

$ curl -X POST "https://copo-project.org/api/profile//make_profile" -H  "accept: */*" -d ""

This creates a profile record for the authenticated user.

Fetch Profile Records

Note

Authentication is required in order to use this API method. Obtain an API token from the following endpoint before using this method:

https://copo-project.org/api/apiKey

https://copo-project.org/api/profile/get_for_user

OR

$ curl -X POST "https://copo-project.org/api/profile/get_for_user" -H  "accept: */*" -d ""

This results in a list of all profiles for the authenticated user.

Statistics’ Endpoints

Fetch Number of COPO Users

https://copo-project.org/api/stats/number_of_users

OR

$ curl -X GET "https://copo-project.org/api/stats/number_of_users" -H  "accept: application/json"

This results in the total number of registered users in COPO.

Fetch Number of Sample Records by Sample Type

https://copo-project.org/api/stats/number_of_samples/{sample_type}

OR

$ curl -X GET "https://copo-project.org/api/stats/number_of_dtol_samples/{sample_type}" -H  "accept: application/json"

This results in the total number of registered sample records in COPO by a given sample type.

Fetch Tree of Life (ToL) Projects Brokered by COPO

https://copo-project.org/api/stats/tol_projects

OR

$ curl -X GET "https://copo-project.org/api/stats/tol_projects" -H  "accept: application/json"

This results in a list of all main/primary projects brokered by COPO.

Fetch Associated Tree of Life (ToL) Projects Brokered by COPO

https://copo-project.org/api/stats/associated_tol_projects

OR

$ curl -X GET "https://copo-project.org/api/stats/associated_tol_projects" -H  "accept: application/json"

This results in a list of all child projects/ subprojects brokered by COPO.

Footnotes