Getting Started

Talis Platform API Basics

This page describes the basics of the Talis Platform API, including examples of how to insert, update, and query data.

Audience

This page is for anyone wishing to understand the XML and RDF formats and protocols that are used by the Talis Platform. It assumes you understand the basics of XML, RDF, and the usage of the GET, POST, PUT, and DELETE request methods of HTTP.

Toolkit

The examples here will be programming language agnostic. You can use any language capable of making HTTP requests, and parsing the XML and RDF responses from the Platform. You can also use CURL for issuing HTTP requests from the command line.

Anatomy of a Talis Platform Store

Each store consists of a Contentbox, for storing documents and binaries, and a Metabox for storing (RDF) Data. The RDF literals in the Metabox can be indexed, and the indexes can be queried via the search and facet services

Examples

Inserting Documents and Binaries into the Contentbox

To insert a document, send it in the body of a POST to http://api.talis.com/stores/{storename}/items

POST /items
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
	<title>A Document for the ContentBox</title>
    </head>
    <body>
        <h1>A Document for the ContentBox</h1>
	<p>Some content ... </p>
    </body>
</html>

Remember to set the appropriate content-type for your document/binary, as the ContentBox will serve the document with that content-type.

The server will respond with something like:

HTTP/1.1 201 Created
Location: http://api.talis.com/stores/{storename}/items/93701cb8-ad40-4e79-b11a-a4b5520d10ba

In one of the headers to the response of your POST request, you will find the new URI that your document will be served at. You can then perform a PUT request to replace it, and a DELETE request to remove it from the Store.

Inserting Data into the MetaBox

To insert your data into the Metabox, just POST it, as RDF/XML or turtle, along with the appropriate content-type (application/rdf+xml or text/turtle)

POST /meta
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
	xmlns:foaf="http://xmlns.com/foaf/0.1/">
    <foaf:Person nodeID="Anna">
	<foaf:name>Anna Wilder</foaf:name>
	<foaf:homepage rdf:resource="http://example.com/">
    </foaf:Person>
</rdf:RDF>

Note that any blank nodes in your data will automatically be assigned to URIs created by the Platform. You can configure the form these URIs will take.

The server will respond with:

HTTP/1.1 204 No Content

Updating Data in the MetaBox

To update the data in your Store's MetaBox, you can send a Changeset document in the body of a POST request to http://api.talis.com/stores/{storename}/meta or http://api.talis.com/stores/{storename}/meta/changesets (the Metabox's Versioned Changeset Collection). With "versioned" changes, the ChangeSet document (if successful), will be stored in the MetaBox with your data. You can use these ChangeSets to view a history of your resource, and rollback the resource to previous states.

POST /meta/changesets
	
<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
          xmlns:cs="http://purl.org/vocab/changeset/schema#">
    <cs:ChangeSet rdf:nodeID="cs">
        <rdf:type rdf:resource="http://purl.org/vocab/changeset/schema#ChangeSet"/>
        <cs:subjectOfChange rdf:resource="http://api.talis.com/stores/mystore/items/thing"/>
        <cs:createdDate>2008-02-06T19:09:20+00:00</cs:createdDate>
        <cs:creatorName>kwijibo</cs:creatorName>
        <cs:changeReason>updating polled data</cs:changeReason>
        <cs:addition rdf:nodeID="a1"/>
        <cs:removal rdf:nodeID="a2"/>
    </cs:ChangeSet>
    <rdf:Statement rdf:nodeID="a1">
        <rdf:subject rdf:resource="http://api.talis.com/stores/mystore/items/thing"/>
        <rdf:predicate rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
        <rdf:object>New Label</rdf:object>
    </rdf:Description>
    <rdf:Statement rdf:nodeID="a2">
        <rdf:subject rdf:resource="http://api.talis.com/stores/mystore/items/thing"/>
        <rdf:predicate rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
        <rdf:object>Old Label</rdf:object>
      </rdf:Description>
</rdf:RDF>

The server will respond with:

HTTP/1.1 204 No Content

Querying a Store's Indexes

You can query a Store's indexes by issuing a GET request to http://api.talis.com/stores/{storename}/items with a query parameter, and (optionally), max, offset, and sort parameters.

The response to this request will be an RSS 1.0 feed, with the results as RSS items, and metadata about the search, such as the max, offset, and sort parameters, and the total number of matching results.

Each item in the results will be a Concise Bounded Description of the matching resource.

GET /items?query=British+Library&max=20&offset=40&sort=title

The server will respond with:

HTTP/1.1 200 OK	
	
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns="http://purl.org/rss/1.0/" 
 xmlns:ns.0="http://purl.org/dc/dcmitype/" 
 xmlns:ns.1="http://xmlns.com/foaf/0.1/" 
 xmlns:ns.2="http://purl.org/dc/terms/" 
 xmlns:relevance="http://a9.com/-/opensearch/extensions/relevance/1.0/" 
 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
 xmlns:os="http://a9.com/-/spec/opensearch/1.1/"  
 xmlns:ns.3="http://schemas.talis.com/2005/dir/schema#" 
 xmlns:ns.4="http://purl.org/dc/elements/1.1/">
  <channel rdf:about="http://api.talis.com/stores/silkworm-dev/items?query=British+Library&max=1">
    <title>British Library</title>
    <link>http://api.talis.com/stores/silkworm-dev/items?query=British+Library&max=1</link>
    <description>Results of a search for British Library on Silkworm public store</description>
    <items>
	<rdf:Seq rdf:about="urn:uuid:33957322-5a5e-451b-bfa8-80719ab55e1a">
		<rdf:li resource="http://directory.talis.com/res/c20060313-id100832#self"/>
	</rdf:Seq>
    </items>
    <os:startIndex>0</os:startIndex>
    <os:itemsPerPage>1</os:itemsPerPage>
    <os:totalResults>21</os:totalResults>
  </channel>
  <item rdf:about="http://directory.talis.com/res/c20060313-id100832#self">
    <title>British Library</title>
    <link>http://directory.talis.com/res/c20060313-id100832#self</link>
    <ns.4:identifier>id100832.natlib</ns.4:identifier>
    <rdf:type>
    	<rdf:Description rdf:about="http://purl.org/dc/dcmitype/Collection"/>
    </rdf:type>
    <ns.2:abstract>The British Library is the national library of the United Kingdom and one of the world's greatest libraries</ns.2:abstract>
    <ns.4:coverage>The collection includes 150 million items, in most known languages increasing at the rate of 3 million new items every year. 
    </ns.4:coverage>
    <relevance:score>0.99999994</relevance:score>
    <ns.4:alternative>British Library</ns.4:alternative>
    <ns.1:homepage>
        <rdf:Description rdf:about="http://www.bl.uk/"/>
    </ns.1:homepage>
    <ns.3:isAccessedVia>
	<rdf:Description rdf:about="http://directory.talis.com/res/pap060331-215#self"/>
    </ns.3:isAccessedVia>
    <ns.4:title>British Library</ns.4:title>
    <ns.3:isAccessedVia>
	<rdf:Description rdf:about="http://directory.talis.com/res/r1146836030081#self"/>
    </ns.3:isAccessedVia>
    <ns.3:etag>887ae76f-62cd-4939-8a1b-ae89d68a98d0</ns.3:etag>
  </item>
</rdf:RDF>

Augmenting the Results of an Index search

You can augment the results of a search on one store, with data from another, by passing the URL of the search on the first store, to the augment service of the second store

GET http://api.talis.com/stores/{second store}/services/augment?data-uri=http://api.talis.com/stores/{first store}/items?query=British+Library

The URL in the data-uri parameter, should of course be URL encoded.

The server will respond with

HTTP/1.1 200 OK

And the body of the response will contain the same RSS 1.0 feed as returned by the query on the first store, but the resource descriptions of the items may be augmented with data from the second store. See Augment Service for more details.

Faceting

GET http://api.talis.com/stores/{storename}/services/facets?query=foaf&fields=title,label,abstract&output=xml

The server will respond with

HTTP/1.1 200 OK
	
<?xml version="1.0"?>
<facet-results xmlns="http://schemas.talis.com/2007/facet-results#">
  <head>
    <query>foaf</query>
    <fields>title,label</fields>
    <top>1</top>
    <output>xml</output>
  </head>
  <fields>
    <field name="title">
      <term value="Using With FOAF" number="3" facet-uri="http://api.talis.com/stores/schema-cache/services/facet?fields=title%2Clabel&top=1&output=xml&query=foaf+AND+title%3A%22Using+With+FOAF%22" search-uri="http://api.talis.com/stores/schema-cache/items?query=foaf+AND+title%3A%22Using+With+FOAF%22"/>
    </field>
    <field name="label">
      <term value="personal mailbox" number="2" facet-uri="http://api.talis.com/stores/schema-cache/services/facet?fields=title%2Clabel&top=1&output=xml&query=foaf+AND+label%3A%22personal+mailbox%22" search-uri="http://api.talis.com/stores/schema-cache/items?query=foaf+AND+label%3A%22personal+mailbox%22"/>
    </field>
  </fields>
</facet-results>

Querying RDF Data in the MetaBox

If you require more powerful/flexible querying of the Metabox than is possible through querying the indexes, you can do this through your store's SPARQL services - http://api.talis.com/stores/{storename}/services/sparql queries the public graph, while http://api.talis.com/stores/{storename}/services/multisparql can query private/named graphs). For more info see: Store SPARQL Service & Store MultiSPARQL Service.

As specified in the SPARQL protocol, SPARQL queries can be issued with either a GET or a POST request:

GET http://api.talis.com/stores/{storename}/services/sparql?query=DESCRIBE+%3Chttp%3A%2F%2Fxmlns.com%2Ffoaf%2F0.1%2F%3E

The server will respond with

200 OK

and your results in the body. The format of the results is determined by the rules governing Output Types and Content Negotiation

Subpages (17): Authentication Authentication FAQ Bounded Descriptions In RDF Capabilities Changeset Protocol Changesets Client Libraries Constructing A Changeset Field Predicate Map Introduction to the Platform Platform FAQ Query Profile SPARQL SPARQL Extensions Store Configuration Store Naming Use of REST

Comments

	Search this site