{scrollbar:icons=false} |
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.
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/cadsrapi41/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
.
Page size information is cached, so that if you make a call that identifies a particular page size, subsequent calls will also use that same page size, even without the parameter. To change the number of results appearing on each page, include a different |
Find a Data Element where Public Id = 2178693 and Version=2.1 and display the basic metadata attributes.
Either the CDE Browser or the caDSR REST API can be used to satisfy this query and results from both are shown below.
Example 1a Results Displayed in the CDE Browser
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, cut and paste it into IE.)
https://cdebrowser.nci.nih.gov/CDEBrowser/search?dataElementDetails=9/&cdeId=2178693&version=2.1&PageId=DataElementsGroup&queryDE=yes&FirstTimer=yes |
Or alternatively
http://freestyle.nci.nih.gov/freestyle/do/cdebrowser?publicId=2178693&version=2.1 |
Sample CDE Browser Output from Example 1
Example 1b Results Displayed in XML
The URL for the results from the caDSR 4.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=DataElement[@publicId=2178693][@version=2.1] |
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.
The URL for the results from the caDSR 4.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=DataElement[@publicId=2178693] |
Sample caDSR REST API XML Output from Example 2
Or the query can retrieve only the latest version
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=DataElement[@publicId=2178693][@latestVersionIndicator=Yes] |
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.
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 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=DataElement&DataElement[@publicId=2178693]&returnHeavyXML=true |
Sample caDSR REST XML Output from Example 3 with "Heavy" XML
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:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=DataElement&DataElementConcept[@publicId=2178546] |
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.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=DataElement&DataElementConcept[@publicId=2178546][@version=2.1] |
Sample caDSR REST XML Output from Example 4 and 5
Find a Form where Public Id = 2392775 and Version=1.0 and display the basic metadata attributes.
Either the Form Builder or the caDSR 4.1 REST-like API can be used to satisfy this query and results from both are shown below.
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.)
The URL for the results from the caDSR 4.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=Form[@publicId=2392775][@version=1.0] |
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.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=Form[@publicId=2392775] |
Find a Form with Public Id = 2392775, display 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 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=Form&Form[@publicId=2392775]&returnHeavyXML=true |
Find all the Forms associated with the CDE with Public Id = 2183364, Version 1.0, display the basic metadata of the Form.
The URL for the results from the caDSR 4.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=Form&Module&Question&DataElement[@publicId=2183364][@version=1.0] |
Get all the modules for form with publicID = 2392775.
The URL for the results from the caDSR 4.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=gov.nih.nci.cadsr.domain.Module&gov.nih.nci.cadsr.domain.Form[@version=1.0][@publicID=2392775] |
Get all the questions for module with publicID = 2392777 and version = 1.0.
The URL for the results from the caDSR 4.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=gov.nih.nci.cadsr.domain.Question&gov.nih.nci.cadsr.domain.Module[@version=1.0][@publicID=2392777] |
Get all the data elements for question with publicID = 2392779 and version = 1.0.
The URL for the results from the caDSR 4.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=gov.nih.nci.cadsr.domain.DataElement&gov.nih.nci.cadsr.domain.Question[@version=1.0][@publicID=2392779] |
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.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetXML?query=AdministeredComponent,AdministeredComponentClassSchemeItem,ClassSchemeClassSchemeItem&ClassSchemeClassSchemeItem[@ID=A55C551C-1866-5ED1-E034-080020C9C0E0] |
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.1 REST API is:
http://cadsrapi.nci.nih.gov/cadsrapi41/GetHTML?query=ClassSchemeClassSchemeItem&ClassSchemeClassSchemeItem[ClassificationScheme[@preferredName=NMDP*]]\ClassificationSchemeItem[@longName=2014r1*] |
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.1 REST API:
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/cadsrapi41/GetHTML?query=DataElement,DataElementConcept,ObjectClass,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C19448]][@primaryFlag=Yes] http://cadsrapi.nci.nih.gov/cadsrapi41/GetHTML?query=DataElement,DataElementConcept,ObjectClass,ConceptDerivationRule&ComponentConcept[Concept[@longName=Blood and Blood Products]][@primaryFlag=Yes] |
http://cadsrapi.nci.nih.gov/cadsrapi41/GetHTML?query=DataElement,DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C42775]][@primaryFlag=Yes] http://cadsrapi.nci.nih.gov/cadsrapi41/GetHTML?query=DataElement,DataElementConcept,Property,ConceptDerivationRule&ComponentConcept[Concept[@longName=E-mail%20Address]][@primaryFlag=Yes] |
http://cadsrapi.nci.nih.gov/cadsrapi41 /GetHTML?query=DataElement,EnumeratedValueDomain,ValueDomainPermissibleValue,PermissibleValue,ValueMeaning,ConceptDerivationRule&ComponentConcept[Concept[@preferredName=C19448]][@primaryFlag=Yes] http://cadsrapi.nci.nih.gov/cadsrapi41 /GetHTML?query=DataElement,EnumeratedValueDomain,ValueDomainPermissibleValue,PermissibleValue,ValueMeaning,ConceptDerivationRule&ComponentConcept[Concept[@longName=Blood and Blood Products]][@primaryFlag=Yes] |
http://cadsrapi.nci.nih.gov/cadsrapi41/GetHTML?query=PermissibleValue,ValueDomainPermissibleValue,EnumeratedValueDomain,ValueDomain&DataElement[@publicID=106][@version=5.1] http://cadsrapi.nci.nih.gov/cadsrapi41/GetHTML?query=PermissibleValue,ValueDomainPermissibleValue,EnumeratedValueDomain,ValueDomain&DataElement[@publicID=106][@latestVersionIndicator=Yes] |
{scrollbar:icons=false} |