CAS Product Server Web APIs (version 2) - User Guide

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:

http://localhost:8080/fmprod/jaxrs...

References

Path:

/reference

Query Parameters:

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:

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

Returns:

A representation of the reference in the requested format

Example URLs:

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

Path:

/product

Query Parameters:

productId (required) - the ID of the product

Available Formats:

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

Returns:

A representation of the product in the requested format

Example URLs:

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

Path:

/dataset

Query Parameters:

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

Available Formats:

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

Returns:

A representation of the dataset in the requested format

Example URLs:

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

Path:

/transfer

Query Parameters:

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

Available Formats:

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

Returns:

A representation of the reference transfer in the requested format

Example URLs:

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

Path:

/transfers

Query Parameters:

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

Available Formats:

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

Returns:

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

Example URLs:

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:

http://localhost:8080/fmprod/...

References

Path:

/data

Query Parameters:

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:

raw data

Returns:

The file for the reference

Example URLs:

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

Notes:

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

Path:

/data

Query Parameters:

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

Available Formats:

application/zip

Returns:

A zip archive of the product's files and metadata

Example URLs:

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

Notes:

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

Path:

/dataset

Query Parameters:

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

Available Formats:

application/zip

Returns:

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:

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

Notes:

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

Path:

/rdf

Query Parameters:

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:

application/xml

Returns:

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

Example URLs:

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

Notes:

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

Path:

/rdf/dataset

Query Parameters:

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:

application/xml

Returns:

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

Example URLs:

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

Notes:

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

Path:

/viewRecent

Query Parameters:

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:

application/xml

Returns:

A representation of the dataset in RSS (XML) format

Example URLs:

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:

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

Path:

/viewRecent

Available Formats:

application/xml

Returns:

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

Example URLs:

http://localhost:8080/fmprod/viewTransfers

Notes:

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:

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

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

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

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

<typesnsmap default="edrn">
  <type name="GenericFile" ns="cas"/>
</typesnsmap>

Example

An example of a complete RDF configuration file is shown below:

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

[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:

<cas:rssconf xmlns:cas="http://oodt.apache.org/ns/cas"
  channelLink="[BaseUrl]?channel=[ProductType]&amp;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:

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

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

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

<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

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