Page History

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:

No Format
/reference

Query Parameters:

No Format
productId (required) - the ID of the product that the reference belongs to refIndex (optional, default 0) - the index of the reference within the product's list of references

Available Formats:

No Format
raw data (.file) application/zip (.zip) application/xml (.xml) application/json (.json) application/rss+xml (.rss)

Returns:

No Format
A representation of the reference in the requested format

Example URLs:

No Format

http://localhost:8080/fmprod/jaxrs/reference?productId=123
http://localhost:8080/fmprod/jaxrs/reference?productId=123&refIndex=4
http://localhost:8080/fmprod/jaxrs/reference.file?productId=123
http://localhost:8080/fmprod/jaxrs/reference.zip?productId=123
http://localhost:8080/fmprod/jaxrs/reference.xml?productId=123
http://localhost:8080/fmprod/jaxrs/reference.json?productId=123
http://localhost:8080/fmprod/jaxrs/reference.rss?productId=123
http://localhost:8080/fmprod/jaxrs/reference.file?productId=123&refIndex=4
http://localhost:8080/fmprod/jaxrs/reference.zip?productId=123&refIndex=2
http://localhost:8080/fmprod/jaxrs/reference.xml?productId=123&refIndex=1
http://localhost:8080/fmprod/jaxrs/reference.json?productId=123&refIndex=0
http://localhost:8080/fmprod/jaxrs/reference.rss?productId=123&refIndex=3

Products

Panel

Path:

No Format
/product

Query Parameters:

No Format
productId (required) - the ID of the product

Available Formats:

No Format
application/zip (.zip) application/xml (.xml) application/json (.json) application/rss+xml (.rss)

Returns:

No Format
A representation of the product in the requested format

Example URLs:

No Format

http://localhost:8080/fmprod/jaxrs/product?productId=123
http://localhost:8080/fmprod/jaxrs/product.zip?productId=123
http://localhost:8080/fmprod/jaxrs/product.xml?productId=123
http://localhost:8080/fmprod/jaxrs/product.json?productId=123
http://localhost:8080/fmprod/jaxrs/product.rss?productId=123

Datasets

Panel

Path:

No Format
/dataset

Query Parameters:

No Format
productTypeId (required) - the product type ID, or "ALL" to denote all product types

Available Formats:

No Format
application/zip (.zip) application/xml (.xml) application/json (.json) application/rdf+xml (.rdf) application/rss+xml (.rss)

Returns:

No Format
A representation of the dataset in the requested format

Example URLs:

No Format

http://localhost:8080/fmprod/jaxrs/dataset?productTypeId=ALL
http://localhost:8080/fmprod/jaxrs/dataset.zip?productTypeId=ALL
http://localhost:8080/fmprod/jaxrs/dataset.xml?productTypeId=ALL
http://localhost:8080/fmprod/jaxrs/dataset.json?productTypeId=ALL
http://localhost:8080/fmprod/jaxrs/dataset.rdf?productTypeId=ALL
http://localhost:8080/fmprod/jaxrs/dataset.rss?productTypeId=ALL
http://localhost:8080/fmprod/jaxrs/dataset?productTypeId=urn:oodt:GenericFile
http://localhost:8080/fmprod/jaxrs/dataset.zip?productTypeId=urn:oodt:LocationAwareProduct
http://localhost:8080/fmprod/jaxrs/dataset.xml?productTypeId=urn:oodt:OtherProduct
http://localhost:8080/fmprod/jaxrs/dataset.json?productTypeId=urn:oodt:ExampleProduct
http://localhost:8080/fmprod/jaxrs/dataset.rdf?productTypeId=urn:oodt:SimpleProduct
http://localhost:8080/fmprod/jaxrs/dataset.rss?productTypeId=urn:oodt:MyProductType

Reference Transfers

Panel

Path:

No Format
/transfer

Query Parameters:

No Format
dataStoreRef (required) - the data store reference for the file being transferred

Available Formats:

No Format
application/xml (.xml) application/json (.json) application/rss+xml (.rss)

Returns:

No Format
A representation of the reference transfer in the requested format

Example URLs:

No Format

http://localhost:8080/fmprod/jaxrs/transfer?dataStoreRef=file:/tmp/test1.txt
http://localhost:8080/fmprod/jaxrs/transfer.xml?dataStoreRef=file:/tmp/test2.txt
http://localhost:8080/fmprod/jaxrs/transfer.json?dataStoreRef=file:/tmp/test3.txt
http://localhost:8080/fmprod/jaxrs/transfer.rss?dataStoreRef=file:/tmp/test4.txt

Product & Dataset Transfers

Panel

Path:

No Format
/transfers

Query Parameters:

No Format
productId (required) - the ID of a product or "ALL" to denote all products

Available Formats:

No Format
application/xml (.xml) application/json (.json) application/rss+xml (.rss)

Returns:

No Format
A representation of the product or dataset transfer in the requested format

Example URLs:

No Format

http://localhost:8080/fmprod/jaxrs/transfers?productId=123
http://localhost:8080/fmprod/jaxrs/transfers.xml?productId=123
http://localhost:8080/fmprod/jaxrs/transfers.json?productId=123
http://localhost:8080/fmprod/jaxrs/transfers.rss?productId=123
http://localhost:8080/fmprod/jaxrs/transfers?productId=ALL
http://localhost:8080/fmprod/jaxrs/transfers.xml?productId=ALL
http://localhost:8080/fmprod/jaxrs/transfers.json?productId=ALL
http://localhost:8080/fmprod/jaxrs/transfers.rss?productId=ALL

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:

No Format
/data

Query Parameters:

No Format
productId (required) - the ID of the product that the reference belongs to refIndex (optional, default 0) - the index of the reference within the product's list of references

Available Formats:

No Format
raw data

Returns:

No Format
The file for the reference

Example URLs:

No Format
http://localhost:8080/fmprod/data?productId=123 http://localhost:8080/fmprod/data?productId=123&refIndex=3

Notes:

No Format
The same path can also be used with the new JAX-RS servlet. For example: http://localhost:8080/fmprod/jaxrs/data?productId=123&refIndex=0

Products

Panel

Path:

No Format
/data

Query Parameters:

No Format
productId (required) - the ID of the product format (required) - must be set to "application/x-zip"

Available Formats:

No Format
application/zip

Returns:

No Format
A zip archive of the product's files and metadata

Example URLs:

No Format
http://localhost:8080/fmprod/data?productId=123&format=application/x-zip

Notes:

No Format
The same path can also be used with the new JAX-RS servlet. For example: http://localhost:8080/fmprod/jaxrs/data?productId=123&format=application/x-zip

Zipped Datasets

Panel

Path:

No Format
/dataset

Query Parameters:

No Format
typeID (required) - the ID of the product type or "ALL" to denote all product types

Available Formats:

No Format
application/zip

Returns:

No Format
A zip archive containing the metadata for the product type, along with zip archives of all products in the dataset, each of which contain the product's files and metadata.

Example URLs:

No Format
http://localhost:8080/fmprod/dataset?typeID=ALL http://localhost:8080/fmprod/dataset?typeID=urn:oodt:GenericFile

Notes:

No Format
The same path can also be used with the new JAX-RS servlet. For example: http://localhost:8080/fmprod/jaxrs/dataset?typeID=ALL

RDF Datasets of Products

Panel

Path:

No Format
/rdf

Query Parameters:

No Format

type (required) - "ALL" to denote all product types, or set to any other value for this parameter to be ignored
id (optional) - the ID of a product type, will be used if the 'type' parameter is set to any other value except "ALL"

Available Formats:

No Format
application/xml

Returns:

No Format
A representation of the dataset in RDF (XML) format.

Example URLs:

No Format
http://localhost:8080/fmprod/rdf?type=ALL http://localhost:8080/fmprod/rdf?type=other&id=urn:oodt:GenericFile

Notes:

No Format

The same path can also be used with the new JAX-RS servlet.
The type parameter is not needed if the id parameter is used.  For example:
http://localhost:8080/fmprod/jaxrs/rdf?type=ALL
http://localhost:8080/fmprod/jaxrs/rdf?id=urn:oodt:GenericFile

RDF Datasets of Product Types

Panel

Path:

No Format
/rdf/dataset

Query Parameters:

No Format

type (required) - "ALL" to denote all product types, or set to any other value for this parameter to be ignored
typeID (optional) - the ID of a product type, will be used if the 'type' parameter is set to any other value except "ALL"

Available Formats:

No Format
application/xml

Returns:

No Format
A representation of the dataset in RDF (XML) format.

Example URLs:

No Format
http://localhost:8080/fmprod/rdf?type=ALL http://localhost:8080/fmprod/rdf?type=other&typeID=urn:oodt:GenericFile

Notes:

No Format

This feature is currently unavailable in new JAX-RS servlet.
The URL can still be used, but it produces an output for product datasets rather than product type datasets.
The type parameter is not needed if the typeID parameter is used.  For example:
http://localhost:8080/fmprod/jaxrs/rdf/dataset?type=ALL
http://localhost:8080/fmprod/jaxrs/rdf/dataset?typeID=urn:oodt:GenericFile

RSS Datasets

Panel

Path:

No Format
/viewRecent

Query Parameters:

No Format

channel (required) - "ALL" to denote all product types, or set to any other value for this parameter to be ignored
id (optional) - the ID of a product type, will be used if the 'channel' parameter is set to any other value except "ALL"
topn (optional, default 20) - limits the number of results in the output

Available Formats:

No Format
application/xml

Returns:

No Format
A representation of the dataset in RSS (XML) format

Example URLs:

No Format

http://localhost:8080/fmprod/viewRecent?channel=ALL
http://localhost:8080/fmprod/viewRecent?channel=ALL&topn=10
http://localhost:8080/fmprod/viewRecent?channel=other&id=urn:oodt:GenericFile
http://localhost:8080/fmprod/viewRecent?channel=other&id=urn:oodt:GenericFile&topn=10

Notes:

No Format

The same path can also be used with the new JAX-RS servlet, but the 'topn' feature has not yet been implemented.
The channel parameter is not needed if the id parameter is used.  For example:
http://localhost:8080/fmprod/jaxrs/viewRecent?channel=ALL
http://localhost:8080/fmprod/jaxrs/viewRecent?id=urn:oodt:GenericFile

Transfers

Panel

Path:

No Format
/viewRecent

Available Formats:

No Format
application/xml

Returns:

No Format
A representation of all current file transfers in RSS (XML) format

Example URLs:

No Format
http://localhost:8080/fmprod/viewTransfers

Notes:

No Format
The same path can also be used with the new JAX-RS servlet. For example: http://localhost:8080/fmprod/jaxrs/viewTransfers

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 xmlns:cas="http://oodt.apache.org/ns/cas">

  <namespace prefix="cas" uri="http://oodt.apache.org/ns/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>

Space shortcuts

Page tree

Versions Compared

Old Version 11

New Version Current

Key

Introduction

URLs (OODT v0.7 onwards)

References

Products

Datasets

Reference Transfers

Product & Dataset Transfers

URLs (all OODT versions)

References

Products

Zipped Datasets

RDF Datasets of Products

RDF Datasets of Product Types

RSS Datasets

Transfers

Configuration Files

RDF Configurations

Namespace Definitions

Metadata Key Renaming

Metadata Keys as Resource Links

Mapping Metadata Keys to Namespaces

Mapping Product Types to Namespaces

Example

RSS

Channel Link Attribute

Namespace Definitions

Tag Definitions

Example