Quick Start
Complete these tasks to set up your environment and use the Global Pathogen Analysis Service (GPAS) REST API to interact with your sample data.
Prerequisites
| Prerequisite | More Information |
| Install cURL | Use cURL |
| Set up authentication | Authenticate |
Task 1: Upload Sample Data to Global Pathogen Analysis Service
This documentation assumes that you have uploaded sample data to GPAS. For more information on uploading sample data, consult the Global Pathogen Analysis Service User Portal Guide.
Note that you can only download files based on the access that has been granted to you.
Task 2: Get Summary Details for Samples
Issue the following cURL command:
curl -X GET -H "Authorization: Bearer <app_access_token>" -H "Content-Type: application/json" -k "<base_url>/get_sample_detail/<sample_name>" --output <file_name>Where:
<app_access_token>is the value obtained from token.json<base_url>is the base URL path for GPAS<sample_name>is a sample name, in alphanumeric format<file_name>is the file name (for example,<sample_name>.json)
An example of the output is as follows:
[
{
"id": "296270265536269181293524698750647976351",
"name": "9cc5b186-0081-7637-2880-1bf389d149f0",
"fileName": null,
"status": "Unreleased",
"instrumentPlatform": "Illumina",
"instrumentModel": null,
"instrumentFlowcell": null,
"uploadedOn": "2022-05-13T13:38:06.294000Z",
"collected": "2022-05-09T00:00:00",
"sampleHost": "human",
"submitterOrganisation": "University of Oxford",
"organisationCoordinator": "user@example.com",
"country": "United Kingdom",
"region": "Unknown",
"district": "Unknown",
"analysis": [
{
"lineageDescription": "B.1.1.7"
}
],
"tags": [
{
"tagName": "GPAS_OxUni",
"tagDescription": "Fictitious sample set created by Oxford University as part of the GPAS project. Share to FN4, grant access to the GPAS organisation, Oracle organisation and Public Repository Data organisation.",
"accessYn": "Y",
"relatednessYn": "Y",
"tag_access": [
{
"organisation_name": "Oracle"
}
]
},
{
"tagName": "HPRU",
"tagDescription": "Fictitious HPRU COVID project: tag shares to FN4 but does not grant access to anyone outside of the University of Oxford",
"accessYn": "N",
"relatednessYn": "Y"
}
]
}
]Task 3: Get Relatedness Details for Samples
Issue the following cURL command:
curl -X GET -H "Authorization: Bearer <app_access_token>" -H "Content-Type: application/json" -k "<base_url>/get_sample_relatedness_detail/<sample_name>" --output <file_name>Where:
<app_access_token>is the value obtained from token.json<base_url>is the base URL path for GPAS<sample_name>is a sample name, in alphanumeric format<file_name>is the file name (for example,<sample_name>.json)
An example of output is as follows:
"9a56e92a-f292-4085-9149-947e3b2c5366":{
"0_snps":{
"ARG":[
"3d331488-6cee-214f-79ba-6bf71191a8b9"
],
"WLF":[
"a4a7cd11-235a-b346-facc-a5cbffdfbda6"
],
"THA":[
"7e769c6d-9d31-a244-c123-6a3e350c2e97"
],
"SHN":[
"9d7dbbd9-2a0f-1e87-1b44-ecc8a32aa73f"
],
"RUS":[
"8c309c05-1236-7096-4ba1-3dcf6129a32d"
],
"PER":[
"7411472c-f985-13be-6191-c7fe19369965"
],
"NIC":[
"0e0d8853-6cc1-890d-5391-33eeba4f806c"
],
"MDA":[
"0a2b599e-5d68-a08d-bb2d-7dcd1ba7ae0c"
],
"HRV":[
"7357668d-b087-529b-1c46-6297ba317cf1"
],
"GRL":[
"1fa9240b-f153-f235-23a0-9e0e93f8eac4"
],
"GBR":[
"0244b624-ffa0-a4a4-6b64-0957021b2c14"
],
"ESP":[
"7c0bb75e-3277-0a8f-a8ae-bb1a18fc17b8"
],
"DOM":[
"17ba8eb1-4e69-43fe-b5bb-72e61e3e0f31"
],
"CZE":[
"03eadf30-662e-4a81-826e-2cc35b518f3d"
],
"COL":[
"cd044670-5c25-568f-3bcd-eb65bd1c7d02"
],
"BRB":[
"4c8fd506-0cbf-103f-f987-e547ad71ad98"
],
"ARM":[
"0f65929f-36b6-2667-7e1c-760ffbd55b88"
]
},
"3_snps":{
"GBR":[
"092fa04a-cd84-428a-b9a5-710dc5c1d06e"
]
}
}
}Task 4: Download Sample Output
Issue the following cURL command:
curl -X GET -H "Authorization: Bearer <app_access_token>" -H "Content-Type: application/json" -k "<base_url>/get_output/<object_name>/<file_type>" --output <file_name>
Where:
<app_access_token>is the value obtained from token.json<base_url>is the base URL path for GPAS<object_name>is a sample or batch name, in alphanumeric format<file_type>is one of the following:- vcf (delivers a zipped file for a batch and a plain text file for a sample)
-
bam (delivers a binary .bam file for a sample)
Note:
You cannot download a .bam file for a batch. - fasta (delivers a zipped file for a batch and a plain text file for a sample)
- fasta_combined (delivers a zipped file for both batches and samples)
- json (delivers a zipped file for a batch and a plain text file for a sample)
- summary_json (delivers a plain text file for both batches and samples)
- pdf (delivers a zipped file for a batch and a PDF for a sample)
- summary_csv (delivers a plain text file for both batches and samples)
- bulk_mutations_csv (delivers a plain text file for both batches and samples)
- mutations_csv (delivers a zipped file for a batch and a plain text file for a sample)
- summary_tsv (delivers a plain text file for both batches and samples)
- bulk_mutations_tsv (delivers a plain text file for both batches and samples)
- mutations_tsv (delivers a zipped file for a batch and a plain text file for a sample)
<file_name>is the file name (for example,<object_name>.<file_type>)
The file and type you specified downloads to your machine.
Task 5: Add a Tag to a Sample
Issue the following cURL command:
curl --location --request POST '<base_url>' \ --header 'Authorization: Bearer <app_access_token>' \ --header 'Content-Type: application/json' \ --data-raw '<input_json>'Where:
<app_access_token>is the value obtained from token.json<base_url>is the base URL path for GPAS-
<input_json>is the JSON object to be passed. For example:{ "tags": ["test", "grant_this_to_Oxford"], "samples": ["6a700746-8a3b-ea1d-038a-49f90dfcd2c3", "9e79b5ed-e583-da70-8154-c444d709cac8"], "reason": "test" }
A message displays, indicating that your update was successful.
Task 6: Update Sample Metadata
Issue the following cURL command:
curl -X POST "<base_url>/update_sample_metadata" -H 'Authorization: Bearer <app_access_token>' -H 'Content-Type: application/json' -d '<input_json>'Where:
<app_access_token>is the value obtained from token.json<base_url>is the base URL path for GPAS-
<input_json>is the JSON object to be passed. For example:{ "samples": ["name": "95d4d8a4-f5c1-b6fa-07f7-8d1620e7e920", "control": "negative", "collection_date": "2022-02-28", "country": "USA", "region": "Texas", "reason": "test" } ] }
A message displays, indicating that your update was successful.
Task 7: Browse the APIs
The main left-side navigation of the API documentation is organized around tasks. If you prefer to browse the API endpoints in a different order:
- Click All REST Endpoints under Introduction.
- Choose one of the Sort by options at the top of the page.