Augment Service

This service augment RDF documents in (rdf+xml and turtle format) by annotating the items in the documents against metadata held in the Store that is performing the augmentation. The RDF document to be augmented can be posted to the Store's augment service or can be retrieved from the web. The Store augment service also augments RSS 1.0 feeds.

The RSS 1.0 feed may be generated by a search against another Platform Store, providing a way to progressively annotate searches against multiple stores using a simple "URL pipeline".

The feed may also be retrieved from the web, providing a means to annotate arbitrary RSS feeds against Platform metadata.

(For RSS feeds only, each store can be configured with a set of rules for detecting items that can be augmented. These augmentations can be done in parallel and merged as RDF or in series, with each store adding a little more data to the results.

Note: currently there is no API access to change the configuration of this feature. Store administrators should contact Talis to request configuration changes.)

URI Pattern

http://api.talis.com/stores/{storename}/services/augment

Resource Operations

URI Pattern	Method	Request Body	Semantics	Capability required
`/services/augment`	GET		Retrieve an HTML form	basic search
`/services/augment?data-uri=`	GET		Augment search results	basic search
`/services/augment`	POST	RSS 1.0, RDF+XML or text/turtle document	Augment search results	basic search

/services/augmentPOSTRSS 1.0, RDF+XML or text/turtle documentAugment search resultsbasic search

Request Parameters

Parameter	Required?	Description	Values
`data-uri`	Yes	The URI of a set of search results in RSS 1.0 format	An absolute URL
`xsl`	No	The URI of an XSLT stylesheet to apply to the results	An absolute URL

Augmenting RDF/XML and Turtle Documents

The Augment Service supports transcoding of results for rdf/xml and turtle. It does not support transcoding of RSS. For example, if the client specifies accept:text/turtle, the client can provide the Augment Service with data that has a content type of application/rdf+xml. For RSS, if the client specifies accept:application/rss+xml then the client must provide a valid RSS feed with a content-type of application/rss+xml.

See here for augmentation content negotiation rules.

Augmenting RSS Feeds

Retrieving the RSS Feed

The data-uri parameter is used to specify the URI of a set of search results in RSS 1.0 format.

The augmentation service will fetch the results at this URI and will automatically follow up to three redirects.

The fetch request will include an Accept header of application/rss+xml if the client accept header is application/rss+xml.

Delivery of Results

Results will be delivered as an RSS 1.0 feed. The annotation just adds additional properties to the items in the feed; the rest of the feed remains intact and untouched.

An XSLT stylesheet can be applied to the results to transform the output into another format. The xsl parameter allows the URI of the stylesheet to be specified and the content-typeparameter identifies the mime type that should be used to deliver the response.

Additional URL parameters will be provided to the XSLT stylesheet. Read the docs for the Transformation Service for additional notes on the XSLT functionality.

Example

As an example, here's a search result document from a store

<rdf:RDF   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
    xmlns:dc="http://purl.org/dc/elements/1.1/" 
    xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns="http://purl.org/rss/1.0/" >
 
  <channel rdf:about="http://api.talis.com/stores/bibstore/items/?query=author:vonnegut+title:breakfast">
    <title>Bigfoot Search Results</title>
    <link>http://api.talis.com/stores/bibstore/items/?query=author:vonnegut+title:breakfast</link>
    <description>query returned 1 item in 65ms</description>
    <items>
      <rdf:Seq rdf:about="http://api.talis.com/stores/bibstore/items/results/00112233-4455-6677-8899-aabbccddeeff">
        <rdf:li resource="http://api.talis.com/stores/bibstore/items/foo"/>
      </rdf:Seq>
    </items>
    <opensearch:totalResults>1</opensearch:totalResults>
    <opensearch:startIndex>1</opensearch:startIndex>
    <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
  </channel>
 
  <item rdf:about="http://api.talis.com/stores/bibstore/items/foo">
    <title>Breakfast Of Champions</title>
    <link>http://api.talis.com/stores/bibstore/items/foo</link>
    <dc:title>Breakfast Of Champions</dc:title>
    <dc:creator>Kurt Vonnegut Jr.</dc:creator>
    <dc:identifier>urn:isbn:0099842602</dc:identifier>
  </item>
 
</rdf:RDF>

Suppose another store contains holdings information and is configured to detect the dc:identifier containing an ISBN. It augments the results with holdings information:

<rdf:RDF   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
    xmlns:dc="http://purl.org/dc/elements/1.1/" 
    xmlns:aug="http://example.com/augmentation#"
    xmlns:hold="http://example.com/holdings#"
    xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns="http://purl.org/rss/1.0/" >
 
  <channel rdf:about="http://api.talis.com/stores/bibstore/items?query=author:vonnegut+title:breakfast">
    <title>Bigfoot Search Results</title>
    <link>http://api.talis.com/stores/bibstore/items/?query=author:vonnegut+title:breakfast</link>
    <description>query returned 1 item in 65ms</description>
    <items>
      <rdf:Seq rdf:about="http://api.talis.com/stores/bibstore/items/results/00112233-4455-6677-8899-aabbccddeeff">
        <rdf:li resource="http://api.talis.com/stores/bibstore/items/foo"/>
      </rdf:Seq>
    </items>
    <opensearch:totalResults>1</opensearch:totalResults>
    <opensearch:startIndex>1</opensearch:startIndex>
    <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
    <aug:augmentation rdf:resource="foo:aug1"/>
  </channel>
 
  <item rdf:about="http://api.talis.com/stores/bibstore/items/foo">
    <title>Breakfast Of Champions</title>
    <link>http://api.talis.com/stores/bibstore/items/foo</link>
    <dc:title>Breakfast Of Champions</dc:title>
    <dc:creator>Kurt Vonnegut Jr.</dc:creator>
    <dc:identifier>urn:isbn:0099842602</dc:identifier>
    <hold:heldBy>
      <hold:Institution rdf:about="http://directory.talis.com/res/institutions/bar">
        <dc:title>First Collection</dc:title>
        <dc:identifier>0000.inst</dc:identifier>
      </hold:Institution>
    </hold:heldBy>
    <hold:heldBy>
      <hold:Institution rdf:about="http://directory.talis.com/res/institutions/baz">
        <dc:title>Second Library Collection</dc:title>
        <dc:identifier>0001.inst</dc:identifier>
      </hold:Institution>
    </hold:heldBy>
 
  </item>
 
  <aug:Augmentation rdf:about="foo:aug1">
    <aug:source rdf:resource="http://api.talis.com/stores/holdings"/>
  </aug:Augmentation>
 
</rdf:RDF>

and this one adds image information:

<rdf:RDF   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
    xmlns:dc="http://purl.org/dc/elements/1.1/" 
    xmlns:aug="http://example.com/aug#"
    xmlns:rich="http://example.com/enrichments#"
    xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns="http://purl.org/rss/1.0/" >
 
  <channel rdf:about="http://api.talis.com/stores/bibstore/items?query=author:vonnegut+title:breakfast">
    <title>Bigfoot Search Results</title>
    <link>http://api.talis.com/stores/bibstore/items/?query=author:vonnegut+title:breakfast</link>
    <description>query returned 1 item in 65ms</description>
    <items>
      <rdf:Seq rdf:about="http://api.talis.com/stores/bibstore/items/results/00112233-4455-6677-8899-aabbccddeeff">
        <rdf:li resource="http://api.talis.com/stores/bibstore/items/foo"/>
      </rdf:Seq>
    </items>
    <opensearch:totalResults>1</opensearch:totalResults>
    <opensearch:startIndex>1</opensearch:startIndex>
    <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
    <aug:augmentation rdf:resource="bla:aug1"/>
  </channel>
 
  <item rdf:about="http://api.talis.com/stores/bibstore/items/foo">
    <title>Breakfast Of Champions</title>
    <link>http://api.talis.com/stores/bibstore/items/foo</link>
    <dc:title>Breakfast Of Champions</dc:title>
    <dc:creator>Kurt Vonnegut Jr.</dc:creator>
    <dc:identifier>urn:isbn:0099842602</dc:identifier>
    <rich:enrichment>
      <rich:Image rdf:about="http://api.talis.com/stores/images/boc_thumbnail.jpg">
        <rich:imageWidth>80</rich:imageWidth>
        <rich:imageHeight>160</rich:imageHeight>
      </rich:Image>
    </rich:enrichment>
    <rich:enrichment>
      <rich:Image rdf:about="http://api.talis.com/stores/images/boc_large.jpg">
        <rich:imageWidth>200</rich:imageWidth>
        <rich:imageHeight>400</rich:imageHeight>
      </rich:Image>
    </rich:enrichment>
  </item>
 
  <aug:Augmentation rdf:about="bla:aug1">
    <aug:source rdf:resource="http://api.talis.com/stores/images"/>
  </aug:Augmentation>
 
</rdf:RDF>

The final merged result might look like this:

<rdf:RDF   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
    xmlns:dc="http://purl.org/dc/elements/1.1/" 
    xmlns:aug="http://example.com/augmentation#"
    xmlns:hold="http://example.com/holdings#"
    xmlns:rich="http://example.com/enrichments#"
    xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
    xmlns="http://purl.org/rss/1.0/" >
 
  <channel rdf:about="http://api.talis.com/stores/bibstore/items?query=author:vonnegut+title:breakfast">
    <title>Bigfoot Search Results</title>
    <link>http://api.talis.com/stores/bibstore/items/?query=author:vonnegut+title:breakfast</link>
    <description>query returned 1 item in 65ms</description>
    <items>
      <rdf:Seq rdf:about="http://api.talis.com/stores/bibstore/items/results/00112233-4455-6677-8899-aabbccddeeff">
        <rdf:li resource="http://api.talis.com/stores/bibstore/items/foo"/>
      </rdf:Seq>
    </items>
    <opensearch:totalResults>1</opensearch:totalResults>
    <opensearch:startIndex>1</opensearch:startIndex>
    <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
    <aug:augmentation rdf:resource="foo:aug1"/>
    <aug:augmentation rdf:resource="bla:aug1"/>
  </channel>
 
  <item rdf:about="http://api.talis.com/stores/bibstore/items/foo">
    <title>Breakfast Of Champions</title>
    <link>http://api.talis.com/stores/bibstore/items/foo</link>
    <dc:title>Breakfast Of Champions</dc:title>
    <dc:creator>Kurt Vonnegut Jr.</dc:creator>
    <dc:identifier>urn:isbn:0099842602</dc:identifier>
    <hold:heldBy>
      <hold:Institution rdf:about="http://directory.talis.com/res/institutions/bar">
        <dc:title>First Collection</dc:title>
        <dc:identifier>0000.inst</dc:identifier>
      </hold:Institution>
    </hold:heldBy>
    <hold:heldBy>
      <hold:Institution rdf:about="http://directory.talis.com/res/institutions/baz">
        <dc:title>Second Library Collection</dc:title>
        <dc:identifier>0001.inst</dc:identifier>
      </hold:Institution>
    </hold:heldBy>
    <rich:enrichment>
      <rich:Image rdf:about="http://api.talis.com/stores/images/boc_thumbnail.jpg">
        <rich:imageWidth>80</rich:imageWidth>
        <rich:imageHeight>160</rich:imageHeight>
      </rich:Image>
    </rich:enrichment>
    <rich:enrichment>
      <rich:Image rdf:about="http://api.talis.com/stores/images/boc_large.jpg">
        <rich:imageWidth>200</rich:imageWidth>
        <rich:imageHeight>400</rich:imageHeight>
      </rich:Image>
    </rich:enrichment>
  </item>
 
  <aug:Augmentation rdf:about="foo:aug1">
    <aug:source rdf:resource="http://api.talis.com/stores/holdings"/>
  </aug:Augmentation>
 
  <aug:Augmentation rdf:about="bla:aug1">
    <aug:source rdf:resource="http://api.talis.com/stores/images"/>
  </aug:Augmentation>
 
 
</rdf:RDF>

Comments