The following topics are included in this page.
(Overview section starts here.)
Using the API, developers can allow an application to connect to caDSR and search the database. The API is available at the Domain Class Browser. The caDSR REST-like (XML-HTTP) API and CDE Browser provide access to, and a means of linking to, caDSR metadata through a standard internet browser.
You cannot enter multiple |
Given a data element, you can retrieve the corresponding EVS concept codes for the values in a Value Domain.
If there is a data element with longName My DE
and the permissible values are Never
, Former
, Current
, etc. and the CDE Browser shows the 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 code."
For example
My DE
) has a getValueDomainPermissibleValueCollectionF
)Former
)Former
has only a Primary Concept)Concept Object
)C0750523
).To search for data elements using a common EVS concept code or name, but restrict the results to only Primary concepts in the CDE object class, refer to the following the examples.
Retrieve data elements with object class, Primary, and concept, Blood and Blood Products (result in XML).
https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,ObjectClass,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C19448]][@primaryFlag=Yes] |
EXTENSION 1: 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 in Example 1 returns 104 results instead of 88.
[@primaryFlag=Yes] |
Retrieve data elements with property Primary, and concept, E-Mail Address.
https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][@primaryFlag=Yes] |
EXTENSION 2: 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 E-Mail address as the primary concept, remove DataElement (the first item in the query argument list in Example 2):
Retrieve DECs with property Primary, and concept E-Mail Address.
https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][@primaryFlag=Yes] |
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] |
(Overview section ends here.)
The following examples find a data element where Public ID = 62 and Version=6, displaying the basic metadata attributes.
This method can be used to retrieve data elements only when you know both the Public ID and Version number. (If you have trouble with the following link in Firefox, copy and paste it into IE.)
https://cdebrowser.nci.nih.gov/CDEBrowser/search?dataElementDetails=9/&cdeId=62&version=6&PageId=DataElementsGroup&queryDE=yes&FirstTimer=yes |
Or alternatively...
https://freestyle.nci.nih.gov/freestyle/do/cdebrowser?publicId=62&version=6 |
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] |
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] |
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] |
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] |
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.
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] |
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] |
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.
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 |
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 all the data elements associated with the DEC with Public ID = 2178546, displaying the basic metadata of the DEC and its data elements.
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] |
The URL for the results from the caDSR II REST API is
https://cadsrapi.cancer.gov/invoke/caDSR/GetHTML?query=DataElement&DataElementConcept[@publicId=2178546] |
The following example finds only data elements associated with Version 2.1 of DEC with Public ID = 2178546.
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] |
The URL for the results from the caDSR II REST API is
https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?DataElement&DataElementConcept[@publicId=2178546,@version=2.1] |
The following examples find a Form where Public ID = 2392775 and Version=1.0, displaying the basic metadata attributes.
This method can be used to retrieve Forms only when you know both the Public ID and Version number. (If you have trouble with the following link in Firefox, copy and paste it into IE.)
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] |
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] |
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.
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] |
The URL for the results from the caDSR II REST API is
https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Form[@publicId=2392775] |
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.
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 |
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 |
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.
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] |
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] |
The following example gets all the modules for a form with Public ID = 2392775.
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] |
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] |
The following example gets all the questions for a module with Public ID = 2392777 and version = 1.0.
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] |
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] |
The following example gets all the data elements for a question with Public ID = 2392779 and version = 1.0.
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] |
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] |
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).
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] |
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] |
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. |
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*] |
The URL for the results from the caDSR II REST API is
TBD |
Examples 15-17 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.
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] |
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] |
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] |
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] |
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] |
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] |
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).
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] |
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] |
The following examples find a concept with the concept code.
https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=Concept[@preferredName=C42614] |
The URL for the results from the caDSR II REST API is
https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=Concept[@preferredName=C42614] |
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] |
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] |
The following caDSR II example retrieves any administered component by public ID.
https://cadsrapi.cancer.gov/invoke/caDSR/GetXML?query=AdministeredComponent[@publicId=62] |
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] |
The following caDSR II example retrieves data elements by public ID and version.
https://cadsrapi.cancer.gov/rad/caDSR.restapi:GetXML_rad/GetXML/query=DataElement[@publicId=62,@version=6] |
(The "Can you retrieve" section starts here.)
Yes. 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.
Example
Retrieve data elements with Object Class “Primary” concept named “Blood and Blood Products” (result in XML).
https://cadsrapi.nci.nih.gov/cadsrapi4/GetXML?query=DataElement,DataElementConcept,ObjectClass,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C19448]][@primaryFlag=Yes] |
EXTENSION 1: An extension finds all data elements where the concept is used either as a primary OR qualifier concept. This is accomplished by removing last qualifier in the query.
[@primaryFlag=Yes] |
Removing this criteria in Example 1 returns 104 results instead of 88.
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] |
EXTENSION 2: 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 in Example 2).
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] |
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] |
(The "Can you retrieve" section ends here.)