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.

Most of the API endpoints can be queried by a desired standard. See the Available Standards for Records table below for the record types that can be queried in each standard. This enhances interoperability since systems may be compliant with other standards.

To query by multiple standards, provide them as a %2C separated in the API URL. %2C is the encoding URL for the comma (,) character.

For example, to query the endpoint in the standards - Darwin Core (DWC), European Nucleotide Archive (ENA) and Minimum Information about any (x) Sequence (MIxS), add the separator to the end of the API URL like this: ?standard=dwc%2Cena%2Cmixs

By default, the API endpoints will return results in the tol (Tree of Life) standard.

Each endpoint results contain metadata provided by the submitter.

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

Available Standards for Records
Standard	Backronym	Available Records Types
dwc	Darwin Core	Sample, Manifest
ena	European Nucleotide Archive	Sample, Manifest
mixs	Minimum Information about any (x) Sequence	Sample, Manifest
tol	Tree of Life	Sample, Manifest

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 Manifests by Sequencing Centre

https://copo-project.org/api/manifest/sequencing_centre?sequencing_centre=<sequencing-centre>

OR

$ curl -X GET "https://copo-project.org/api/manifest/sequencing_centre?sequencing_centre=<sequencing-centre>" -H  "accept: application/json"

This results in a list of manifest IDs [4] that are associated with the given sequencing_centre. In the API URL, replace <sequencing-centre> with the name of the sequencing centre.

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 in a Manifest 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 a 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.
To query by multiple associated project types, provide them as a %2C separated in the API URL. %2C is the URL encoding for the comma (,) character.

For example, to query the endpoint for the associated project types BGE and ERGA_PILOT, add BGE%2CERGA_PILOT like this: sample/associated_tol_project/BGE%2CERGA_PILOT to the end of the API URL.

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

OR

$ curl -X GET "https://copo-project.org/api/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 Project Fields by Manifest Version

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 sample fields by project and manifest version.

If no manifest version is provided, the latest manifest version is used. If no project is provided, all project types are used.

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 Accession

Note

A biosample accession is a unique identifier (ID) that is assigned to a sample record by ENA [9] after the sample has been accepted by a sample manager [10].
The biosampleAccession is referred to as biosampleAccession in COPO and biosample_id in ENA.
To query by multiple biosample accessions, provide them as a %2C separated in the API URL in this endpoint. %2C is the encoding URL for the comma (,) character.

For example, to query sample records by the biosample accessions - SAMEA12816320, SAMEA115502883, SAMEA112168601 and SAMEA112168603, add SAMEA12816320%2CSAMEA115502883%2CSAMEA112168601%2CSAMEA112168603 to the end of the API URL like this: sample/biosampleAccession/SAMEA12816320%2CSAMEA115502883%2CSAMEA112168601%2CSAMEA112168603 .

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

OR

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

This results in full sample information for the sample record returned from the given {biosampleAccessions}.

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 Sample Records by Sequencing Centre

https://copo-project.org/api/sample/sequencing_centre?sequencing_centre=<sequencing-centre>

OR

$ curl -X GET "https://copo-project.org/api/sample/sequencing_centre?sequencing_centre=<sequencing-centre>" -H  "accept: application/json"

This results in full sample information for the sample records based on the given sequencing_centre. In the API URL, replace <sequencing-centre> with the name of the sequencing centre.

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 and Date

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

OR

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

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

If no sample type is provided and no start date and end date are provided, COPO will return the total number of samples.

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