Augment Service

From n² wiki

Jump to: navigation, search

This is the Platform API documentation for the Augmentation service.

This service augments RSS 1.0 feeds by annotating the items in the feed against metadata held in the Store that is performing the augmentation.

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.

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.

Contents

[edit] URI Pattern

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

[edit] 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 document Augment search results basic search

[edit] 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
content-type No The content type for delivering the response A mime media type

[edit] Augmenting RSS Feeds

[edit] 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 only.

[edit] Annotation Against the Store

TODO

[edit] 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-type parameter 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.

[edit] 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>
Retrieved from "http://n2.talis.com/wiki/Augment_Service"
Personal tools