Introduction
The CAS Product Server web application allows information about file manager entities such as references, products and file transfers to be retrieved via a RESTful interface. It is a read-only service using HTTP GET methods and returning HTTP responses with status code 200 (OK) if successful. This guide gives brief details on the URL scheme used by the web application and on custom configuration files that can be used to modify outputs for certain entities in certain formats.
URLs (OODT v0.7 onwards)
The paths given in this section assume a base path of http://<host>/<web application>/<sevlet>
, where <host>
is the Tomcat server's URL, <web application>
is the path to the deployed CAS Product Server web application, and <servlet>
is the path to the JAX-RS servlet (jaxrs). For example:
No Format |
---|
http://localhost:8080/fmprod/jaxrs...
|
References
Panel | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
|
Products
Panel | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
|
Datasets
Panel | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
|
Reference Transfers
Panel | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
|
Product & Dataset Transfers
Panel | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
|
URLs (all OODT versions)
The paths given in this section assume a base path of http://<host>/<web application>, where <host> is the Tomcat server's URL, <web application> is the path to the deployed CAS Product Server web application. For example:
No Format |
---|
http://localhost:8080/fmprod/...
|
References
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
Notes:
|
Products
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
Notes:
|
Zipped Datasets
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
Notes:
|
RDF Datasets of Products
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
Notes:
|
RDF Datasets of Product Types
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
Notes:
|
RSS Datasets
Panel | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Path:
Query Parameters:
Available Formats:
Returns:
Example URLs:
Notes:
|
Transfers
Panel | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Path:
Available Formats:
Returns:
Example URLs:
Notes:
|
Configuration Files
The web application allows certain output formats (currently RDF and RSS) to be customized via XML configuration files. Below is a brief description of these files. Further information can be found in the example files supplied with the web application in the src/main/resources subdirectory.
RDF Configurations
The RDF configuration file is split into several sections as described below.
Namespace Definitions
This section is used to define namespaces. The <namespaces>
parent element encloses the section and <ns>
child elements are used to define individual namespaces. Each <ns>
element has two attributes, name to store the namespace prefix and value to store the namespace URL. For example:
No Format |
---|
<namespaces>
<ns name="cas" value="urn:oodt:"/>
<ns name="rdf" value="http://www.w3.org/1999/02/22-rdf-syntax-ns#"/>
<ns name="edrn" value="urn:edrn:"/>
<ns name="x" value="http://edrn.nci.nih.gov/rdf/schema.rdf#"/>
</namespaces>
|
Metadata Key Renaming
This section is used to rename metadata keys in the output RDF. The <rewrite>
parent element encloses the section and <key>
child elements are used to rename individual metadata keys. Each <key>
element has two attributes, from to specify the original name for the metadata key and to to specify the new name for the metadata key. For example:
No Format |
---|
<rewrite>
<key from="SiteId" to="site"/>
<key from="SiteName" to="site"/>
<key from="ProtocolId" to="protocol"/>
<key from="OrganId" to="organ"/>
<key from="OrganSite" to="organ"/>
<key from="ProtocolName" to="protocol"/>
</rewrite>
|
Metadata Keys as Resource Links
This section is used to specify that certain metadata keys should be used as resource links. The <resourceLinks>
parent element encloses the section and <key>
child elements are used to identify individual metadata keys. Each <key>
element has two attributes, name to specify the metadata key and link to specify the URL for the link. For example:
No Format |
---|
<resourcelinks>
<key name="SiteId" link="http://edrn.nci.nih.gov/data/sites/"/>
<key name="SiteName" link="http://edrn.nci.nih.gov/data/sites/"/>
<key name="ProtocolId" link="http://edrn.nci.nih.gov/data/protocols/"/>
<key name="ProtocolName" link="http://edrn.nci.nih.gov/data/protocols/"/>
<key name="OrganId" link="http://edrn.nci.nih.gov/data/body-systems/"/>
<key name="OrganSite" link="http://edrn.nci.nih.gov/data/body-systems/"/>
</resourcelinks>
|
Mapping Metadata Keys to Namespaces
This section is used to map metadata keys to the namespaces declared in the <namespaces>
section. The <keynsmap>
parent element encloses the section. This element must have a default attribute set to the default namespace to use. The <key>
child elements are used to map individual metadata keys. Each <key>
element has two attributes, name to specify the metadata key and ns to specify the namespace name, which must be defined in the <namespaces>>
section. For example:
No Format |
---|
<keynsmap default="edrn">
<key name="CAS.ProductId" ns="cas"/>
<key name="CAS.ProductName" ns="cas"/>
<key name="CAS.ProductReceivedTime" ns="cas"/>
<key name="FileLocation" ns="cas"/>
<key name="Filename" ns="cas"/>
<key name="ProductType" ns="cas"/>
<key name="DataVersion" ns="cas"/>
<key name="MimeType" ns="cas"/>
<key name="SiteId" ns="x"/>
<key name="SiteName" ns="x"/>
<key name="ProtocolName" ns="x"/>
<key name="ProtocolId" ns="x"/>
<key name="OrganId" ns="x"/>
<key name="OrganSite" ns="x"/>
</keynsmap>
|
Mapping Product Types to Namespaces
The final section maps product type names to previously declared namespaces. The <typesnsmap>
parent element encloses the section. This element must have a default attribute set to the default namespace to use. The <type>
child elements are used to map individual product types. Each <type>
element has two attributes, name to specify the product type name and ns to specify the namespace name, which must be defined in the <namespaces>>
section. For example:
No Format |
---|
<typesnsmap default="edrn">
<type name="GenericFile" ns="cas"/>
</typesnsmap>
|
Example
An example of a complete RDF configuration file is shown below:
No Format |
---|
<cas:rdfconf xmlns:cas="http://oodt.apache.org/ns/cas">
<namespaces>
<ns name="cas" value="urn:oodt:"/>
<ns name="rdf" value="http://www.w3.org/1999/02/22-rdf-syntax-ns#"/>
<ns name="edrn" value="urn:edrn:"/>
<ns name="x" value="http://edrn.nci.nih.gov/rdf/schema.rdf#"/>
</namespaces>
<rewrite>
<key from="SiteId" to="site"/>
<key from="SiteName" to="site"/>
<key from="ProtocolId" to="protocol"/>
<key from="OrganId" to="organ"/>
<key from="OrganSite" to="organ"/>
<key from="ProtocolName" to="protocol"/>
</rewrite>
<resourcelinks>
<key name="SiteId" link="http://edrn.nci.nih.gov/data/sites/"/>
<key name="SiteName" link="http://edrn.nci.nih.gov/data/sites/"/>
<key name="ProtocolId" link="http://edrn.nci.nih.gov/data/protocols/"/>
<key name="ProtocolName" link="http://edrn.nci.nih.gov/data/protocols/"/>
<key name="OrganId" link="http://edrn.nci.nih.gov/data/body-systems/"/>
<key name="OrganSite" link="http://edrn.nci.nih.gov/data/body-systems/"/>
</resourcelinks>
<keynsmap default="edrn">
<key name="CAS.ProductId" ns="cas"/>
<key name="CAS.ProductName" ns="cas"/>
<key name="CAS.ProductReceivedTime" ns="cas"/>
<key name="FileLocation" ns="cas"/>
<key name="Filename" ns="cas"/>
<key name="ProductType" ns="cas"/>
<key name="DataVersion" ns="cas"/>
<key name="MimeType" ns="cas"/>
<!-- EDRN example -->
<key name="SiteId" ns="x"/>
<key name="SiteName" ns="x"/>
<key name="ProtocolName" ns="x"/>
<key name="ProtocolId" ns="x"/>
<key name="OrganId" ns="x"/>
<key name="OrganSite" ns="x"/>
</keynsmap>
<typesnsmap default="edrn">
<type name="GenericFile" ns="cas"/>
</typesnsmap>
</cas:rdfconf>
|
RSS
Channel Link Attribute
An optional channelLink attribute can be set on the outer tag of the configuration file to customize the RSS channel element's link attribute. In addition to other characters, the value of the channelLink attribute can contain the following metadata keys surrounded by square brackets:
No Format |
---|
[BaseUrl] - replaced by the base URL of the CAS Product Server web application
[ProductType] - replaced by the value of the 'channel' parameter in the request URL
[ProductTypeId] - replaced by the value of the 'id' parameter in the request URL
[TopN] - replaced by the value of the 'topn' parameter in the request URL
|
An example is shown below:
No Format |
---|
<cas:rssconf xmlns:cas="http://oodt.apache.org/ns/cas"
channelLink="[BaseUrl]?channel=[ProductType]&id=[ProductTypeId]">
|
Namespace Definitions
Namespaces are defined using a <namespace>>
element with a prefix attribute (for the namespace prefix) and a uri attribute (for the namespace URI). For example:
No Format |
---|
<namespace prefix="cas" uri="http://oodt.apache.org/ns/cas"/>
<namespace prefix="georss" uri="http://www.georss.org/georss"/>
|
Tag Definitions
Tags are defined using a <tag>
element with a required name attribute (to specify the name of the element in the output RSS) and an optional source attribute (to specify the element's text value in the output RSS). For example:
No Format |
---|
<tag name="cas:source" source="[ProductType]"/>
<tag name="source" source="[ProductType]"/>
|
Tags can also have child <attribute>
elements that can be used to specify additional attributes for the output RSS element. Each <attribute>
element must have a name attribute (to specify the attribute's name in the RSS output tag element) and a value attribute (to specify the attribute's value in the RSS output tag element. For example:
No Format |
---|
<tag name="enclosure">
<attribute name="url" value="http://localhost:8080/fmprod/jaxrs/reference.file?productID=[CAS.ProductId]"/>
<attribute name="length" value="[FileSize]"/>
<attribute name="type" value="audio/mpeg"/>
</tag>
|
Example
An example of a complete RSS configuration file is shown below:
No Format |
---|
<cas:rssconf |
Download a product (by ID) from the eCAS REST API
Sample REST URL
http://host/fmprod/data?productID=<UUID>
Parameters
No Format |
---|
''query:''
'''productId''' ''<UUID>''
'''format''' (optional) ''application/x-zip''
|
Response
No Format |
---|
HTTP 200 OK
- Raw Data Content if format is not application/x-zip
- Zipped Data Content containing product .met XML file,
along with raw data content
|
== Download an entire datast (by ID) from the eCAS REST API ==
=== Sample REST URL ===
http://edrn.jpl.nasa.gov/fmprodp3/dataset?typeID=urn:edrn:FHCRCHanashAnnexinLamr
=== Parameters ===
''query:''
'''typeID''' ''<A valid product type name>''
=== Response ===
HTTP 200 OK
- Zipped Data Content containing product zip files containing
their .met XML files, along with raw data content
== Get an RDF stream of current datasets from eCAS ==
=== Sample REST URL ===
https://edrn.jpl.nasa.gov/fmprodp3/rdf/dataset?filter=LeadPI:Samir%20Hanash&type=ALL
=== Parameters ===
''query:''
'''type''' ''<A valid product type name, or ALL to denote all of them>''
'''typeID''' ''<A valid product type id; only use this when not using ALL>''
'''filter''' (optional) ''A query in Lucene-style syntax to limit returned
RDF to only those datasets that match the filter
criteria''
=== Response ===
HTTP 200 OK
- MIME: application/x-rdf
- RDF description of all matching datasets for filter if
provided, for all datasets, if ALL is used, or as
identified by type and typeID.
==== Sample ====
<?xml version="1.0" ?>
<rdf:RDF xmlns:cas="urn:oodt:" xmlns:edrn="urn:edrn:"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:x="http://edrn.nci.nih.gov/rdf/schema.rdf#">
<edrn:WHIColonUniversityofMichiganChinnaiyan
rdf:about="http://edrn.jpl.nasa.gov/fmprodp3//dataset/ID">
<edrn:Date>
2011-08-30T03:46:00.000Z
</edrn:Date>
<edrn:PubMedID>
TBD
</edrn:PubMedID>
<x:protocol
rdf:resource="http://edrn.nci.nih.gov/data/protocols/126"/>
<edrn:DataCustodian>
Arul Chinnaiyan
</edrn:DataCustodian>
</edrn:WHIColonUniversityofMichiganChinnaiyan>
</rdf:RDF>
== Get an RDF stream of current products from eCAS ==
=== Sample REST URL ===
=== Parameters ===
''query:''
'''type''' ''<A valid product type name, or ALL to denote all of them>''
'''id''' ''<A valid product type id; only use this when not using ALL>''
=== Response ===
HTTP 200 OK
- MIME: application/x-rdf
- RDF description of all matching product metadata for all
products, if ALL is used, or as identified by type and
id.
==== Sample ====
<?xml version="1.0" ?>
<rdf:RDF xmlns:cas="urn:oodt:" xmlns:edrn="urn:edrn:"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:x="http://edrn.nci.nih.gov/rdf/schema.rdf#">
<edrn:WHIColonKarmanosCancerInstituteTainsky
rdf:about="http://edrn.jpl.nasa.gov/fmprodp3//data?productID=..">
<edrn:ProductDescription>
TBD
</edrn:ProductDescription>
<edrn:SpecimenType>
Plasma
</edrn:SpecimenType>
<cas:FileLocation>
/data/archive/kci/110901/Colon/Unknown
</cas:FileLocation>
<cas:CAS.ProductName>
EDRN_WHI_Tainsky-rawData.csv
</cas:CAS.ProductName>
<edrn:DateProductFrozen>
TBD
</edrn:DateProductFrozen>
</edrn:WHIColonKarmanosCancerInstituteTainsky>
</rdf:RDF>
== Get an RSS 2.0 feed of current products from eCAS ==
=== Sample REST URL ===
https://edrn.jpl.nasa.gov/fmprodp3/viewRecent?channel=ALL
=== Parameters ===
''query:''
'''channel''' ''<A valid product type name, or ALL to denote all of them>''
'''id''' ''<A valid product type id; only use this when not using ALL>''
'''topn''' ''The number, by default 20, of results to show''
=== Response ===
HTTP 200 OK
- MIME: application/x-rss
- RSS description of all matching product metadata and link
for all products, if ALL is used, or as identified by type
and id.
...
xmlns:cas="http://oodt. |
...
apache. |
...
org/ns/cas"> |
...
<namespace prefix="cas" uri="http:// |
...
oodt. |
...
apache. |
...
org/ |
...
ns/ |
...
</item>
</channel>
...
cas"/>
<tag name="cas:source" source="[ProductType]"/>
<tag name="source" source="[ProductType]"/>
<tag name="enclosure">
<attribute name="url"
value="http://localhost:8080/fmprod/data.mp3?productID=[CAS.ProductId]"/>
<attribute name="length" value="[FileSize]"/>
<attribute name="type" value="audio/mpeg"/>
</tag>
<namespace prefix="georss" uri="http://www.georss.org/georss"/>
<tag name="georss:point" source="[Latitude] [Longitude]"/>
</cas:rssconf>
|