Page History

...

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-like (XML-HTTP) API and CDE Browser provide access to, and a means of linking to, caDSR metadata through a standard internet browser.

caDSR REST-like 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-like (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.

Determining Result Set Size and Pagination of REST-like API Results

All caDSR APIs are generated using the caCORE SDK. For REST-like APIs, the SDK provides the ability to determine the number of total results returned from a query, along with the ability to determine how many results are shown on each page.

The caDSR REST-like API allows for the use of the resultCounter parameter. By default, the result set is limited to 1000 records, with 10 CDE records appearing per page. Since the caDSR API does not request a login, these paging settings are global and cannot be configured or retained per user. Instead, use the result set and pagination parameters described here to configure your API calls.

To change the maximum number of results returned for a query, add the resultCounter=## parameter to the call. To change the number of results shown per page, add the pageSize=## parameter to the call. All of the Example queries shown on this page can be appended with the resultCounter and pageSize parameters.

For example:

http://cadsrapi.nci.nih.gov/cadsrapi40/GetXML?query=gov.nih.nci.cadsr.domain.Form&gov.nih.nci.cadsr.domain.Form[@workflowStatusName=RELEASED]&startIndex=0&pageSize=30&resultCounter=300

Logically, if your total results are less than the page size, the first page of results will contain all returned items.

You can also add the startIndex parameter to indicate which record should be the first on the page. This means you can alter a query to return the second or third page of results. Generally speaking, however, the startIndex parameter is "zero based" - you start at zero and subsequent pages begin with a startIndex of the next result page. Using the above query as an example, the second page of the results would show startIndex=31.

Examples

Example 1 - Find Data Element by Public ID and Version

...

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 -

...

Retrieve

...

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

http://cadsrapi.nci.nih.gov/cadsrapi40/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.

...

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.)

...

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

Example

...

14 - 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.

...

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

Examples 15-17  - Get Data Elements using Concept Code or Concept Name

The Examples

...

15-

...

17 below show retrieving 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 are returned in HTML. All URL's are using the caDSR 4.0 REST API:

Example

...

15 - Find all Data Elements where associated concept is the Primary Concept of the 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 HTML.

http://cadsrapi.nci.nih.gov/cadsrapi40/GetHTML?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]

Example

...

16 - Find all Data Elements where associated concept is the Primary Concept of the Data Element's Property.

http://cadsrapi.nci.nih.gov/cadsrapi40/GetHTML?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]

Example

...

17 - Find all Data Elements where associated concept is the Primary Concept of one of the Data Element's Value Domain Value Meanings.

http://cadsrapi.nci.nih.gov/cadsrapi40
/GetHTML?query=DataElement,EnumeratedValueDomain,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]

Example

...

18 - Find all enumerated Permissible Values for a Data Element using Data Element public id and version or using Data Element public id (and getting latest version)

http://cadsrapi.nci.nih.gov/cadsrapi40/GetHTML?query=PermissibleValue,ValueDomainPermissibleValue,EnumeratedValueDomain,ValueDomain&DataElement[@publicID=106][@version=5.1]

http://cadsrapi.nci.nih.gov/cadsrapi40/GetHTML?query=PermissibleValue,ValueDomainPermissibleValue,EnumeratedValueDomain,ValueDomain&DataElement[@publicID=106][@latestVersionIndicator=Yes]

...