View Source

The following topics are included in this page.

Overview

You can view or search for caDSR data by entering a URL in the address bar of a browser and passing parameters in that URL. This page provides examples to get you started, in legacy and caDSR II format:

A URL in legacy REST-like (XML-HTTP) format returns only HTML or XML. The Domain Class Browser page is a web browser interface that allows you to test the legacy caDSR API. This page also has links to the Legacy Java Docs.
A URL in caDSR II format returns HTML, XML, or JSON. Using the API, you can allow an application to connect to caDSR and search the database.

You can display any of these formats (HTML, XML, or JSON) in an Internet browser by changing the parameter (GetHTML, GetXML, or GetJSON).

You cannot enter multiple "and" or "in" values for search criteria when using the REST (XML-HTTP) API.

If you have trouble using any URL on this page in your Internet browser, copy and paste it into another browser. (The caDSR team tests functionality in Chrome.)

Examples in caDSR II but not Legacy caDSR

Headings on this page marked with two asterisks (**) reflect functionality available in caDSR II but not in legacy caDSR.

Examples for Data Elements

Find Data Element by Public ID and Version

The following examples find a data element where Public ID = 62 and Version=6, displaying the basic metadata attributes.

Legacy: Results Displayed in XML

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement[@publicId=62][@version=6]

caDSR II: Results Displayed in XML

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=DataElement[@publicId=62,@version=6]

caDSR II: Results Displayed in HTML

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetHTML?query=DataElement[@publicId=62,@version=6]

caDSR II: Results Displayed in JSON

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetJSON?query=DataElement[@publicId=62,@version=6]

**Allow Machine-to-machine Retrieval of a Data Element by Public ID and Version

The following caDSR II example allows machine-to-machine retrieval of a data element by public ID and version.

https://cadsrapi.cancer.gov/rad/caDSR.restapi:GetXML_rad/GetXML/query=DataElement[@publicId=62,@version=6]

If you want to create a REST API call from machine to machine or application to application, start your URL as follows:

https://cadsrapi.cancer.gov/rad/caDSR.restapi:GetXML_rad/

Find Data Element by Public ID

The following example finds a data element with Public ID = 62, displaying the basic metadata attributes. Since the version is not known, this query can only be handled via a caDSR REST API query getting all versions.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetHTML?query=DataElement[@publicId=62]

Or the query can retrieve only the latest version.

https://cadsrapi.nci.nih.gov/cadsrapi4/GetHTML?query=DataElement[@publicId=62][@latestVersionIndicator=Yes]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetHTML?query=DataElement[@publicId=62]

Or the query can retrieve only the latest version.

https://cadsrapi.cancer.gov/invoke/caDSR/GetHTML?query=DataElement[@publicId=62,@latestVersionIndicator=yes]

Find Data Element by Public ID, Display All Related Components

The following example finds a data element with Public ID = 62, displaying all the metadata associated with the data element's related components, not just the basic attributes. This is handled in the caDSR REST API using a parameter that produces expanded ("heavy") XML.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement&DataElement[@publicId=62]&returnHeavyXML=true

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=DataElement[@publicId=62]&returnHeavyXML=true

Find DEC Using Public ID, Display All Associated Data Elements

Find all the data elements associated with the DEC with Public ID = 2178546, displaying the basic metadata of the DEC and its data elements.

Legacy

The URL for the results from the caDSR 4.0 REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetHTML?query=DataElement&DataElementConcept[@publicId=2178546]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetHTML?query=DataElement&DataElementConcept[@publicId=2178546]

Find Data Elements Associated with a Particular DEC Public ID and Version

The following example finds only data elements associated with Version 2.1 of DEC with Public ID = 2178546.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement&DataElementConcept[@publicId=2178546][@version=2.1]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=DataElement&DataElementConcept[@publicId=2178546,@version=2.1]

Get Data Elements Using Concept Code or Concept Name

The following examples show how to retrieve data elements using either the concept code or the concept name where the concept is the Primary concept of the related caDSR item. In these examples, results are returned in XML.

Legacy: Find All Data Elements Where Associated Concept is Primary Concept of Data Element's Object Class

This example shows the use of either the Concept Code (C19448) or the Concept Name "Blood and Blood Products". Results are identical from these two calls, both are returned in XML.

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,ObjectClass,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C19448]][@primaryFlag=Yes]

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,ObjectClass,ConceptDerivationRule&ComponentConcept[Concept[@longName=Blood and Blood Products]][@primaryFlag=Yes]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=DataElement,DataElementConcept,ObjectClass&ComponentConcept[Concept[@preferredName=C19448],@primaryFlag=Yes]

Legacy: Find All Data Elements Where Associated Concept is Primary Concept of Data Element's Property

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C42775]][@primaryFlag=Yes]

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][@primaryFlag=Yes]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=DataElement,DataElementConcept,Property&ComponentConcept[Concept[@preferredName=C42775],@primaryFlag=Yes]

Legacy: Find All Data Elements Where Associated Concept is Primary Concept of One of Data Element's Value Domain Value Meanings

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,EnumeratedValueDomain,ValueDomainPermissibleValue,PermissibleValue,ValueMeaning,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C19448]][@primaryFlag=Yes]

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,EnumeratedValueDomain,ValueDomainPermissibleValue,PermissibleValue,ValueMeaning,ConceptDerivationRule&ComponentConcept[Concept[@longName=Blood and Blood Products]][@primaryFlag=Yes]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=DataElement,ValueDomain,ValueDomainPermissibleValue,PermissibleValue,ValueMeaning&ComponentConcept[Concept[@preferredName=C19448],@primaryFlag=Yes]

Find All Enumerated Permissible Values for a Data Element

The following examples find all enumerated permissible values for a data element using the data element's public ID and version or the data element's public ID (and getting latest version).

Legacy

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=PermissibleValue,ValueDomainPermissibleValue,EnumeratedValueDomain,ValueDomain&DataElement[@publicId=106][@version=5.1]

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=PermissibleValue,ValueDomainPermissibleValue,EnumeratedValueDomain,ValueDomain&DataElement[@publicId=106][@latestVersionIndicator=Yes]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=PermissibleValue,ValueDomainPermissibleValue,ValueDomain&DataElement[@publicId=106,@version=5.1]

Examples for Forms and Related Items

Find a Form Using Form Public ID and Version, Display Basic Metadata Attributes

The following examples find a Form where Public ID = 2392775 and Version=1.0, displaying the basic metadata attributes.

Legacy: Results Displayed in the Form Builder

This method can be used to retrieve Forms only when you know both the Public ID and Version number.

https://formbuilder.nci.nih.gov/FormBuilder/formDetailsAction.do?method=getFormDetails&formIdSeq=FF04F699-FE6A-56AA-E034-0003BA3F9857

Legacy: Results Displayed in XML

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=Form[@publicId=2392775][@version=1.0]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Form[@publicId=2392775,@version=1]

Find a Form Using Only Public ID

The following example finds a Form with Public ID = 2392775, displaying the basic metadata attributes. Since the version is not known, this query can only be handled via a caDSR REST API query.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=Form[@publicId=2392775]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Form[@publicId=2392775]

Find a Form Using Public ID, Display All Metadata Associated with Data Elements

The following example finds a Form with Public ID = 2392775, displaying all the metadata associated with the data element's related components, not just the basic attributes. This is handled in the caDSR REST API using a parameter that produces expanded ("heavy") XML.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=Form&Form[@publicId=2392775]&returnHeavyXML=true

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Form[@publicId=2392775]&returnHeavyXML=true

Find All Forms Associated with Particular Data Element Public ID and Version

The following example finds all the Forms associated with the CDE with Public ID = 2183364, Version 1.0, displaying the basic metadata of the Form.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=Form&Module&Question&DataElement[@publicId=2183364][@version=1.0]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Form,Module,Question&DataElement[@publicId=2183364,@version=1.0]

Get all Modules Associated with a Form Using Form Public ID

The following example gets all the modules for a form with Public ID = 2392775.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=gov.nih.nci.cadsr.domain.Module&gov.nih.nci.cadsr.domain.Form[@version=1.0][@publicId=2392775]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Module&Form[@publicId=2392775,@version=1.0]

Get All the Questions for a Module Using Module Public ID and Version

The following example gets all the questions for a module with Public ID = 2392777 and version = 1.0.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=gov.nih.nci.cadsr.domain.Question&gov.nih.nci.cadsr.domain.Module[@version=1.0][@publicId=2392777]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Question&Module[@publicId=2392777,@version=1.0]

Get All the Data Elements for Question Using Question Public ID and Version

The following example gets all the data elements for a question with Public ID = 2392779 and version = 1.0.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=gov.nih.nci.cadsr.domain.DataElement&gov.nih.nci.cadsr.domain.Question[@version=1.0][@publicId=2392779]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=DataElement&Question[@publicId=2392779,@version=1.0]

**Retrieve a caDSR Form with All Its Collections ("Flattened")

The following caDSR II examples retrieve a caDSR form with all its collections, or "flattened". This means for a given form, the system returns all Modules, Questions, Valid Values and related instructions in one call. The system returns results as a JSON file. XML and HTML formats are not available for this query. You must specify a version.

The following example retrieves a form without specifying a protocol:

https://cadsrapi.cancer.gov/invoke/form.test/getJSON?query=Form[@publicId=7203785,@version=1]

The following example specifies a protocol:

https://cadsrapi.cancer.gov/invoke/form.test/getJSON?query=Form[Protocol[@preferredName=C3D%20ADOPTER%20TEMPLATES],@publicId=2392775,@version=1]

Return Form by Public ID and Protocol

The following caDSR II example retrieves forms with protocol by public ID.

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Form[Protocol[@preferredName=C3D ADOPTER TEMPLATES],@publicId=2392775]

Examples for Value Meaning Concepts

Retrieving the Value Meaning Concept Codes for a Data Element That Has an Enumerated Value Domain

Given a data element, you can retrieve the corresponding concept codes for the permissible values in a Value Domain.

If there is a data element with longName My DE and the permissible values are N=Never, F=Former, C=Current, and so on, and the CDE Browser shows the concept code for Never as C70543, Former as C0750523, and Current as C25471, your application can navigate the objects starting at the value domain and work to the corresponding concept code.

For example

Each Data Element (My DE) that is enumerated has an EnumeratedValueDomain that can be retrieved using getValueDomain.
Each EnumeratedValueDomain has a permissible value list that can be retrieved using getValueDomainPermissibleValueCollection.
Each ValueDomainPermissibleValue in the collection has a getPermissibleValue, in this example (F).
Each permissibleValue has a getValueMeaning (Former).
Each valueMeaning has a getConceptDerivationRule which stores the list of concepts and their ordering.
Each conceptDerivationRule has a getComponentConceptCollection (the primary concept and any qualifier concepts, in this case Former has only a Primary Concept).
Each componentConcept in the collection has a getConcept (returns the Concept Object).
Each concept has an attribute, preferredName which stores the corresponding concept code (C0750523).

Retrieving a caDSR Item That Has Concept Using the Concept Code or Name, but Restricting the Search to Only Retrieving Items if the Concept is the Primary Concept

To search for data elements using a concept code or name, but restrict the results to only Primary concepts in the Object Class, refer to the following examples.

Legacy

Retrieve data elements with Object Class Concept "C19448" (result in XML) but only if the Concept is indicated as the Primary concept. This is done using the Concept's primaryFlag indicator = "Yes".

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,ObjectClass,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C19448]][@primaryFlag=Yes]

caDSR II

https://cadsrapi.cancer.gov/caDSR5.0/GetXML?query=DataElement,DataElementConcept,ObjectClass,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C19448],@primaryFlag=Yes]

Both Legacy and caDSR II

Additionally, you can find all Data Elements where the concept is used either as a primary OR qualifier concept. This is accomplished by removing the last qualifier in the query. Removing this criteria returns 104 results instead of 88.

[@primaryFlag=Yes]

Legacy

Retrieve Data Elements with Property having the Primary Concept with the longName E-Mail Address.

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][@primaryFlag=Yes]

caDSR II

https://cadsrapi.cancer.gov/caDSR5.0/GetXML?query=DataElement,DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address],@primaryFlag=Yes]

Legacy

To retrieve the next higher order "type" administered items, remove the name of the item(s) before it in the query argument list. For example, to get Data Element Concepts (DECs) with its Property Primary Concept longName E-Mail Address, remove DataElement (the first item in the query argument list):

Retrieve DECs with Property Primary Concept name E-Mail Address.

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][@primaryFlag=Yes]

caDSR II

https://cadsrapi.cancer.gov/caDSR5.0/GetXML?query=DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][@primaryFlag=Yes]

Legacy

Retrieve Data Elements with its ValueDomain having a ValueMeaning with a Primary Concept longName Blood and Blood Products (result in XML).

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,EnumeratedValueDomain,ValueDomainPermissibleValue,PermissibleValue,ValueMeaning,ConceptDerivationRule&ComponentConcept[Concept[@longName=Blood and Blood Products]][@primaryFlag=Yes]

caDSR II

https://cadsrapi.cancer.gov/caDSR5.0/GetXML?query=DataElement,EnumeratedValueDomain,ValueDomainPermissibleValue,PermissibleValue,ValueMeaning,ConceptDerivationRule&ComponentConcept[Concept[@longName=Blood and Blood Products]][@primaryFlag=Yes]

Examples for Other Items

Retrieve All Administered Components Associated with ClassSchemeClassSchemeItem with Particular ID

The following example gets all Administered Components for ClassSchemeClassSchemeItem with ID = A55C551C-1866-5ED1-E034-080020C9C0E0. This retrieves all ACs and sorts them according to type (Form, DE, DEC, and so on).

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=AdministeredComponent,AdministeredComponentClassSchemeItem,ClassSchemeClassSchemeItem&ClassSchemeClassSchemeItem[@ID=A55C551C-1866-5ED1-E034-080020C9C0E0]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=AdministeredComponent,AdministeredComponentClassSchemeItem&ClassSchemeClassSchemeItem[@id=A55C551C-1866-5ED1-E034-080020C9C0E0]

Retrieve All ClassSchemeClassSchemeItem Associated with ClassificationSchemeItem and ClassificationScheme

The following example gets all ClassSchemeClassSchemeItem for ClassificationSchemeItem with longName starting with 2014r1 and ClassificationScheme with preferredName starting with NMDP.

The association can be specified either through using square brackets '[]' or by using the backslash '\' however, association within the square brackets cannot have further associations as attributes.

Legacy

The URL for the results from the caDSR 4.1.x REST API is

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=ClassSchemeClassSchemeItem&ClassSchemeClassSchemeItem[ClassificationScheme[@preferredName=NMDP*]]\ClassificationSchemeItem[@longName=2014r1*]

Find a Concept by Concept Code

The following examples find a concept with the concept code.

Legacy

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=Concept[@preferredName=C42614]

caDSR II

The URL for the results from the caDSR II REST API is

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Concept[@preferredName=C42614]

**Return Permissible Value Info Including Associated Concepts for a CDE

The following caDSR II example returns the Permissible Value information for a given CDE. If you do not specify the version, the query returns the latest version.

https://cadsrapi.cancer.gov/caDSR/GetPVXML01?query=PermissibleValue&DataElement[@publicId=62,@version=6]

Retrieving Any Administered Component by Public ID

The following examples retrieve any administered component by public ID.

Legacy

https://cadsrapi.nci.nih.gov/cadsrapi41/GetHTML?query=gov.nih.nci.cadsr.domain.AdministeredComponent&gov.nih.nci.cadsr.domain.AdministeredComponent[@publicID=62]

caDSR II

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=AdministeredComponent[@publicId=62]

Retrieve all Data Elements Using a Common EVS Concept Code or Name, but Restrict Results to Only Those Where the Concept is “Primary” in the CDE’s Object Class

This can be done through any of the caDSR APIs, as well as for restricting to Property or a Value Meaning in the CDEs Enumerated Value Domain.

Legacy: Retrieve data elements with Object Class “Primary” concept with concept code "C19448" (result in XML).

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,ObjectClass,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C19448]][@primaryFlag=Yes]

To find all data elements where the concept is used either as a primary OR qualifier concept, remove last qualifier in the query.

[@primaryFlag=Yes]

Removing this criteria returns 104 results instead of 88.

Legacy: Retrieve data elements with Property “Primary” concept named “E-Mail Address”.

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][@primaryFlag=Yes]

To retrieve the next higher order "type" administered items, remove the name of the item(s) before it in the query argument list, for example, to get DECs with E-Mail address as the primary concept, remove "DataElement" (the first item in the query argument list).

Legacy: Retrieve DECs with Property “Primary” concept named “E-Mail Address”.

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][@primaryFlag=Yes]

Legacy: Retrieve data elements with Value Domain's Value Meaning "Primary" concept code= C19448 (Blood and Blood Products”) (result in XML).

https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,EnumeratedValueDomain,ValueDomainPermissibleValue,PermissibleValue,ValueMeaning,ConceptDerivationRule&ComponentConcept[Concept[@longName=Blood and Blood Products]][@primaryFlag=Yes]

caDSR II: Retrieve all Data Elements where the Object Class “Primary” concept is concept code "C19448" (result in XML).

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=DataElement,DataElementConcept,ObjectClass&ComponentConcept[Concept[@preferredName=C19448],@primaryFlag=Yes]

caDSR II: Retrieve all Data Elements where the Object Class “Primary” concept is concept name "E-mail Address" (result in XML).

https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=DataElement,DataElementConcept,Property&ComponentConcept[Concept[@longName=E-mail%20Address],@primaryFlag=Yes]