NIH | National Cancer Institute | NCI Wiki  

Versions Compared

Old Version 98

changes.mady.by.user Unknown User (wileyal)

Saved on

compared with

New Version Current

changes.mady.by.user Frost, Ruth (NIH/NCI) [C]

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Enclosed contents of page in Lorenzo's custom macro instead of the standard numbered headings macro.

Include Page
caDSR API Examples Overview include
caDSR API Examples Overview include

This page includes the following topics.

Wiki Markup
{scrollbar:icons=false}

...

Custom nh
start-numbering-with1
start-numbering-ath2

...

this
Panel
titleContents of
This Page

Table of Contents

minLevel2
Section
Column
Panel
titleQuick Links
Column  Include PageCommonProjects:Included Page of CBIIT and NCIP LinksCommonProjects:Included Page of CBIIT and NCIP Links

Overview

Using the API, developers can allow an application to connect to caDSR and search the database. The API is available for download.

The caDSR REST (XML-HTTP) API and CDE Browser provide access to, and a means of linking to, caDSR metadata through a standard internet browser.

caDSR REST results can be displayed HTML in either or XML format - XML and can be displayed in an internet browser or by means of an XSLT stylesheet. The caDSR 4.0 Technical Guide describes the caDSR REST (XML-HTTP) API and provides a catalog of the caDSR operations and search criteria. To switch formats simply change the URL in the address line from "getHTML" to "getXML.

A few examples in both XML and HTML of caDSR operations are provided below. The attached MS Word documents for the examples show sample results and the "http" statements used to produce the results, and provide information about how to interpret the results. See also the REST API FAQs.

Examples

maxLevel3

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

...

.

...

Example 1 Results Displayed in the CDE Browser

...

 

...

Code Block
https://cdebrowser.nci.nih.gov/CDEBrowser/search?dataElementDetails=9/&cdeId=2178693&version=2.1&PageId=DataElementsGroup&queryDE=yes&FirstTimer=yes

Or alternatively

Code Block
http://freestyle.nci.nih.gov/freestyle/do/cdebrowser?publicId=2178693&version=2.1

Sample CDE Browser Output from Example 1

Results Displayed in XML

The URL for the results from the caDSR

...

II REST API is

...

Code Block
http
https://cadsrapi.
nci
cancer.
nih.
gov/
cadsrapi40
invoke/caDSR/GetXML?query=DataElement[@publicId=
2178693][
62,@version=
2.1
6]

Example 2 - Find Data Element by Public ID

Find a Data Element with Public Id = 2178693, display the basic metadata attributes, version is not known.

Since the version is not known, this query can only be handled via a caDSR REST API query getting all versions.

Results Displayed in HTML

The URL for the results from the caDSR

...

II REST API is

...

Code Block
http
https://cadsrapi.
nci
cancer.
nih.
gov/
cadsrapi40/GetXML?query=DataElement[publicId=2178693]

Sample caDSR REST API XML Output from Example 2

Or the query can retrieve only the latest version

Code Block
http://cadsrapi.nci.nih.gov/cadsrapi40/GetXML
invoke/caDSR/GetHTML?query=DataElement[
publicId=2178693][@latestVersionIndicator=Yes]

Example 3 - Find Data Element by Public Id, display all related components

Find a Data Element with Public Id = 2178693, display all the metadata associated with the Data Element's related components, not just the basic attributes.

...

@publicId=62,@version=6]

Results Displayed in JSON

The URL for the results from the caDSR

...

II REST API is

...

Code Block
http
https://cadsrapi.
nci
cancer.
nih.
gov/invoke/
cadsrapi40
caDSR/
GetXML
GetJSON?query=
DataElement&
DataElement[@publicId=62,@version=
2178693
6]
&returnHeavyXML=true

Sample caDSR REST XML Output from Example 3 with "Heavy" XML

Example 4 - Find Data Element Concept using public ID and display all its associated Data Elements

Find all the Data Elements associated with the Data Element Concept with Public Id = 2178546, display the basic metadata of the Data Element Concept and its Data Elements.

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

Code Block
http://cadsrapi.nci.nih.gov/cadsrapi40/GetXML?query=DataElement&DataElementConcept[@publicId=2178546]

Example 5 - Find Data Elements associated with a particular Data Element Concept public ID and Version

Find only Data Elements associated with VERSION 2.1 of Data Element Concept with Public Id = 2178546.

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

Code Block
http://cadsrapi.nci.nih.gov/cadsrapi40/GetXML?query=DataElement&DataElementConcept[@publicId=2178546][@version=2.1]

Sample caDSR REST XML Output from Example 4 and 5

Example 6 - Find a Form using Form public ID and Version and display basic metadata attributes

Find a Form where Public Id = 2392775 and Version=1.0 and display the basic metadata attributes.

Either the Form Builder or the caDSR REST API can be used to satisfy this query and results from both are shown below.

Example 6 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.  (If you have trouble with the following link in Firefox, cut and paste it into IE.)

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

Example 6 Results Displayed in XML

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. (You can test this URL only in a machine-to-machine scenario, not in a browser.)

Code Block
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: 

Code Block
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.

The URL for the results from the caDSR

...

II REST API is

...

Code Block
http
https://cadsrapi.
nci
cancer.
nih.
gov/
cadsrapi40
invoke/caDSR/
GetXML
GetHTML?query=
Form
DataElement[@publicId=
2392775][@version=1.0]

Example 7 - Find a Form using only public id

Find a Form with Public Id = 2392775, display the basic metadata attributes, version is not known.

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.0 REST API is:

62]

Or the query can retrieve only the latest version.

Code Block
https
Code Block
http
://cadsrapi.
nci
cancer.
nih.
gov/invoke/
cadsrapi40
caDSR/
GetXML
GetHTML?query=
Form[publicId=2392775
DataElement[@publicId=62,@latestVersionIndicator=yes]

Example 8 - Find a Form using public id, display all the metadata associated with the Data Elements

...

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.

The URL for the results from the caDSR

...

II REST API is

...

Code Block
http
https://cadsrapi.
nci
cancer.
nih.
gov/
cadsrapi40
invoke/caDSR/GetXML?query=
Form&Form
DataElement[@publicId=
2392775
62]&returnHeavyXML=true

Example 9 - Find all the Forms associated with a particular Data Element public id and version

...

Find DEC Using Public ID, Display All Associated Data Elements

The following example finds 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

...

II REST API is

...

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

Example 10 - Get all Modules associated with a Form using Form public id.

Get all the modules for form with publicID = 2392775.

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

Code Block
http://cadsrapi.nci.nih.gov/cadsrapi40/GetXML?query=gov.nih.nci.cadsr.domain.Module&gov.nih.nci.cadsr.domain.Form[@version=1.0][@publicID=2392775]

Example 11 - Get all the Questions for a Module using Module public id and version.

Get all the questions for module with publicID = 2392777 and version = 1.0.

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

Code Block
http://cadsrapi.nci.nih.gov/cadsrapi40/GetXML?query=gov.nih.nci.cadsr.domain.Question&gov.nih.nci.cadsr.domain.Module[@version=1.0][@publicID=2392777]

Example 12 - Get all the Data Elements for a Question using Question public id and version.

Get all the data elements for question with publicID = 2392779 and version = 1.0.

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

Code Block
http://cadsrapi.nci.nih.gov/cadsrapi40/GetXML?query=gov.nih.nci.cadsr.domain.DataElement&gov.nih.nci.cadsr.domain.Question[@version=1.0][@publicID=2392779]

Example 13 - Set the number of records to be retrieved.

...

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.

The URL for the results from the caDSR

...

II REST API is

...

Code Block
http
https://cadsrapi.
nci.nih
cancer.gov/
cadsrapi40
invoke/caDSR/GetXML?query=
gov.nih.nci.cadsr.domain.Form&gov.nih.nci.cadsr.domain.Form[@workflowStatusName=RELEASED]&startIndex=0&pageSize=300&resultCounter=300

NOTE: Since there are no logins, the paging settings are global. Users should not rely on the current settings but should explicitly set startIndex, pageSize, and resultCounter on each query.

Example 14 - Retrieve all Administered Components associated with a ClassSchemeClassSchemeItem with a particular ID.

Get all Administered Components for ClassSchemeClassSchemeItem with ID = A55C551C-1866-5ED1-E034-080020C9C0E0
This will retrieve all AC's and sort them according to type (Form, DE, DEC, etc.)

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

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

Example 15 - Retrieve all ClassSchemeClassSchemeItem associated with a ClassificationSchemeItem and a ClassificationScheme.

Get all ClassSchemeClassSchemeItem for ClassificationSchemeItem with longName starting with 2014r1
and ClassificationScheme with preferredName starting with NMDP
Note, 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.0 REST API is:

Code Block
http://cadsrapi.nci.nih.gov/cadsrapi40/GetHTML?query=ClassSchemeClassSchemeItem&ClassSchemeClassSchemeItem[ClassificationScheme[@preferredName=NMDP*]]\ClassificationSchemeItem[@longName=2014r1*]

...

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. 

Find All Data Elements Where Associated Concept is Primary Concept of

...

Data Element's Object Class

...

This example shows the use of

...

the Concept Code (C19448)

...

. Results are

...

returned in

...

XML.

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

Code Block
http
https://cadsrapi.
nci
cancer.
nih.
gov/
cadsrapi40
invoke/caDSR/
GetHTML
GetXML?query=DataElement,DataElementConcept,ObjectClass
,ConceptDerivationRule
&ComponentConcept[Concept[@preferredName=C19448]
][@primaryFlag=Yes] http://cadsrapi.nci.nih.gov/cadsrapi40/GetHTML?query=DataElement,DataElementConcept,ObjectClass
,
ConceptDerivationRule&ComponentConcept[Concept[@longName=Blood and Blood Products]][
@primaryFlag=Yes]

...

Find

...

All Data Elements

...

Where Associated Concept is Primary Concept of

...

Data Element's Property

...

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

Code Block
http
https://cadsrapi.
nci
cancer.
nih.
gov/
cadsrapi40
invoke/caDSR/
GetHTML
GetXML?query=DataElement,DataElementConcept,Property
,ConceptDerivationRule
&ComponentConcept[Concept[@preferredName=C42775]
][@primaryFlag=Yes] http://cadsrapi.nci.nih.gov/cadsrapi40/GetHTML?query=DataElement,DataElementConcept,Property
,
ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][
@primaryFlag=Yes]

...

Find

...

All Data Elements

...

Where Associated Concept is Primary Concept of

...

One of

...

Data Element's Value Domain Value Meanings

...

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

Code Block
http
https://cadsrapi.
nci.nih
cancer.gov/
cadsrapi40 /GetHTML
invoke/caDSR/GetXML?query=DataElement,
EnumeratedValueDomain
ValueDomain,ValueDomainPermissibleValue,PermissibleValue,ValueMeaning
,ConceptDerivationRule
&ComponentConcept[Concept[@preferredName=C19448
]
]
[@primaryFlag=Yes] http://cadsrapi.nci.nih.gov/cadsrapi40 /GetHTML?query=DataElement,EnumeratedValueDomain
,
ValueDomainPermissibleValue,PermissibleValue,ValueMeaning,ConceptDerivationRule&ComponentConcept[Concept[@longName=Blood and Blood Products]][
@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). You must specify either version or latestVersionIndicator. If you specify latestVersionIndicator=No, the query returns all permissible values across all versions of the CDE.

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

Code Block
http
https://cadsrapi.
nci.nih
cancer.gov/
cadsrapi40
invoke/caDSR/
GetHTML
GetXML?query=PermissibleValue,ValueDomainPermissibleValue,
EnumeratedValueDomain,
ValueDomain&DataElement[
@publicID
@publicId=106
][
,@version=5.1]
http
https://cadsrapi.
nci
cancer.
nih.
gov/
cadsrapi40
invoke/caDSR/
GetHTML
GetXML?query=PermissibleValue,ValueDomainPermissibleValue
,EnumeratedValueDomain
,ValueDomain&DataElement[
@publicID
@publicId=106
][
,@latestVersionIndicator=Yes]

Wiki Markup
{scrollbar:icons=false}