Skip Navigation
NIH | National Cancer Institute | NCI Wiki   New Account Help Tips
Skip to end of metadata
Go to start of metadata

You can print and export wiki pages

You can send this page to a printer or convert it to a PDF, HTML, or Word document. See Printing and Exporting Wiki Pages.

This document explains the basics of using the TCGA's Barcode to UUID Web Services.

Contents of this Page
Getting Support

Overview

UUID REST web services are designed so that other applications that need to use these services have a programmatic way of doing so. This interface allows you to carry out UUID-related functions without resorting to the GUI interface. This service accepts single UUID queries through a GET request and up to 500 UUIDs through a POST request.

Currently the following REST web services are implemented:

Response Formats

The web service response can be received either in XML or JSON format depending on the URL being used.

JSON format: The URL in the following format returns a JSON response:

GET request: 
https://tcga-data.nci.nih.gov/uuid/uuidws/<service_function>/json/
POST request:
https://tcga-data-dev.nci.nih.gov/uuid/uuidws/mapping/json/<service_function>/batch

XML format: The URL in the following format returns an XML response:

GET request:
https://tcga-data.nci.nih.gov/uuid/uuidws/<service_function>/xml/
POST request:
https://tcga-data-dev.nci.nih.gov/uuid/uuidws/mapping/xml/<service_function>/batch

Services

Currently, the Barcode-to-UUID mapping REST web service is implemented.

URL Encoding

All URLs sent to DCC web services must have proper URL encoding of reserved characters. For example, the ampersand character (@) in an email address must be URL encoded as %40.

Barcode-to-UUID Mapping

This web service provides a method to search a barcode for its corresponding UUID and vice versa. There are two versions of this service, a GET version that searches individual barcodes or UUIDs and a POST version that can search up to 500 barcodes or UUIDs in a query.

Search by Barcode

If a legacy barcode (that is, a deprecated barcode) is searched, the UUID that is returned will be the same as the one with which its latest active barcode is associated.

Searches using the GET method

Note

A wildcard search is allowed. Add * at the end of a valid barcode to search all UUIDs with an associated barcode that starts by the entered barcode.

Example links:

For JSON response:https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/barcode/TCGA-02-0001
For JSON response (using wildcard):https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/barcode/TCGA-02-0001\* (https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/barcode/TCGA-02-0001*)

For XML response:https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/barcode/TCGA-02-0001
For XML response (using wildcard):https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/barcode/TCGA-02-0001\* (https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/barcode/TCGA-02-0001*)

Searches using the POST method

Note

A wildcard searches are not allowed when using the POST method

For searches using the POST method, the media type must be set to "text/plain" and the body of the request should contain up to 500 UUIDs, each separated by a comma.

curl Examples

For JSON response: curl -k -X POST --data "barcode1,barcode2,barcode3,barcode4" --header "Content-Type: text/plain" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/barcode/batch

For XML response: curl -k -X POST --data "barcode1,barcode2,barcode3,barcode4" --header "Content-Type: text/plain" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/barcode/batch

For JSON response(Barcodes in a file): curl -k -X POST --data @barcodes_for_mapping.txt --header "Content-Type: text/plain" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/barcode/batch

For XML response(Barcodes in a file): curl -k -X POST --data @barcodes_for_mapping.txt --header "Content-Type: text/plain" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/barcode/batch

wget Examples

For JSON response: wget --header="Content-Type: text/plain" --post-data="barcode1,barcode2,barcode3,barcode4" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/barcode/batch -O wget_results.json

For XML response: wget --header="Content-Type: text/plain" --post-data="barcode1,barcode2,barcode3,barcode4" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/barcode/batch -O wget_results.xml

For JSON response(Barcodes in a file): wget --header="Content-Type: text/plain" --post-file=barcode_file.txt https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/barcode/batch -O wget_results.json

For XML response(Barcodes in a file): wget --header="Content-Type: text/plain" --post-file=barcode_file.txt https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/barcode/batch -O wget_results.xml

Search by UUID

Legacy barcodes (that is, deprecated barcodes) are not returned using this method; only the latest revision of a barcode is returned when a UUID is queried.

Searches using the GET method

Example links:

Searches using the POST method

For searches using the POST method, the media type must be set to "text/plain" and the body of the request should contain up to 500 UUIDs, each separated by a comma.

curl Examples

For JSON response: curl -k -X POST --data "uuid1,uuid2,uuid3,uuid4" --header "Content-Type: text/plain" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/uuid/batch

For XML response: curl -k -X POST --data "uuid1,uuid2,uuid3,uuid4" --header "Content-Type: text/plain" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/uuid/batch

For JSON response(Barcodes in a file): curl -k -X POST --data @uuids_for_mapping.txt --header "Content-Type: text/plain" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/uuid/batch

For XML response(Barcodes in a file): curl -k -X POST --data @uuids_for_mapping.txt --header "Content-Type: text/plain" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/uuid/batch

wget Examples

For JSON response: wget --header="Content-Type: text/plain" --post-data="uuid1,uuid2,uuid3,uuid4" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/uuid/batch -O wget_results.json

For XML response: wget --header="Content-Type: text/plain" --post-data="uuid1,uuid2,uuid3,uuid4" https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/uuid/batch -O wget_results.xml

For JSON response(UUIDs in a file): wget --header="Content-Type: text/plain" --post-file=uuid_file.txt https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/json/uuid/batch -O wget_results.json

For XML response(UUIDs in a file): wget --header="Content-Type: text/plain" --post-file=uuid_file.txt https://tcga-data.nci.nih.gov/uuid/uuidws/mapping/xml/uuid/batch -O wget_results.xml

Example POST Responses

JSON Example

{"uuidMapping":[{"barcode":"TCGA-BH-A0H6-10A-01W-A071-09","uuid":"6ddf4ce5-5956-4394-af6e-f840573ac67e"},
{"barcode":"TCGA-AN-A0AK-10A-01W-A021-09","uuid":"9243b0f3-5c29-4922-902c-8348cd53537c"},
{"barcode":"TCGA-A2-A04T-10A-01W-A055-09","uuid":"9482fe83-a4b1-424a-baf1-8b0f8e40c9b7"},
{"barcode":"TCGA-AA-A00O-10A-01W-A00E-09","uuid":"97de82c4-87ea-4811-832b-c17ebb966539"},
{"barcode":"TCGA-AG-A002-10A-01W-A005-10","uuid":"db7ea780-0ce0-4831-82ea-0afe0be9df6b"}]}

XML Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<uuidBarcodeMappings>
	<uuidMapping>
		<barcode>TCGA-BH-A0H6-10A-01W-A071-09</barcode>
		<uuid>6ddf4ce5-5956-4394-af6e-f840573ac67e</uuid>
	</uuidMapping>
	<uuidMapping>
		<barcode>TCGA-AN-A0AK-10A-01W-A021-09</barcode>
		<uuid>9243b0f3-5c29-4922-902c-8348cd53537c</uuid>
	</uuidMapping>
	<uuidMapping>
		<barcode>TCGA-A2-A04T-10A-01W-A055-09</barcode>
		<uuid>9482fe83-a4b1-424a-baf1-8b0f8e40c9b7</uuid>
	</uuidMapping>
	<uuidMapping>
		<barcode>TCGA-AA-A00O-10A-01W-A00E-09</barcode>
		<uuid>97de82c4-87ea-4811-832b-c17ebb966539</uuid>
	</uuidMapping>
	<uuidMapping>
		<barcode>TCGA-AG-A002-10A-01W-A005-10</barcode>
		<uuid>db7ea780-0ce0-4831-82ea-0afe0be9df6b</uuid>
	</uuidMapping>
</uuidBarcodeMappings>

Query Frequency Limitation

The UUID Web Service has a query limitation of 1000 queries every 3 minutes (this applies to both the GET and POST methods). Exceeding this quota will cause the system to return HTTP Status Code 413 until the system again falls below the quota limit.

Error Codes

Error codes appear in the response header.

Error Code

Query Type

Description

500

GET

Barcode or UUID given in the URL was not found

405 Method Not Allowed

POST

Attempted to use a GET query to a POST service

415 Unsupported Media Type.

POST

The "media type" of the query was not set to "text/plain"

422 Unprocessable Entity

POST

The query body is either empty or some barcodes/UUIDs are invalid. In the later case the returned message will contain the invalid entries in the requested format (JSON or XML)