This URI represents a store's Metabox, the part of a store designed for holding structured metadata in the form of an RDF graph. This RDF can be queried using the Store Sparql Service or the Store Multisparql Service. The Metabox presents the primary RDF graph within a Store. There may be additional graphs associated with a Store. These graphs can be separately queried and updated. A list of the graphs can be obtained from the Private Graphs Collection. URI Patternhttp://api.talis.com/stores/{storename}/meta
|
| URI Pattern | Method | Mime Type(s) | Semantics | Capability required |
|---|---|---|---|---|
| /{storename}/meta | GET | Return resource query form | basic search | |
| /{storename}/meta?about= | GET | Describe the identified resource | basic search | |
| /{storename}/meta | POST | application/rdf+xml or text/turtle | Used for Storing RDF in the Metabox | full update |
| POST | application/vnd.talis.changeset+xml orapplication/vnd.talis.changeset+turtle | Apply a Changeset to metabox. See Updating and Batch Updating. | full update |
Request Parameters
| Parameter | Required? | Description | Values |
|---|---|---|---|
| about | No | Identify a resource to describe | Resource URI |
| output | No | Specify the Output Type |
|
Describing a Resource
GETs to the metabox require the basic search capability.
If no parameters are supplied, this service responds with an HTML form to assist creating the correct set of parameters.
Optional Parameters
- about - a URI. When supplied the response will be an RDF document containing a description of the resource identified by the URI supplied in this parameter. The description consists of all triples in the metabox that have a subject equal to the supplied URI.
- output - defines the particular output type required for the RDF description document. Supported values are:
- rdf - response is always an RDF/XML document with content type of application/rdf+xml (default if parameter is omitted)
- xml - response is an RDF/XML document with content type of application/xml
- ntriples - response is an nTriples document with content type of text/plain
- turtle - response is an Turtle document with content type of text/turtle
- json - response is an RDF/JSON document with content type of application/json (see RDF/JSON Specification)
Conditional GETs are supported so clients can ask for descriptions to only be sent if they are different to the one the client saw last time. This can enable clients to cache descriptions efficiently.
If no output parameter is supplied then the service will respond to content negotiation using the request's Accept header.
Storing RDF
POSTing new data to the metabox requires the full update capability. RDF documents are currently accepted in either RDF/XML or Turtle, and requests must include a Content-Type header with the value application/rdf+xml or text/turtle respectively (the deprecated application/x-turtle media-type is also supported, but not preferred). Other RDF serializations are not yet supported, but will be added later.
By default, any blank nodes in RDF added to the metabox via POST are replaced with generated URIs. Any relative URIs will also be replaced with generated URIs (of the form http://api.talis.com/stores/{storename}/items/{relative URI}). Use of xml:base is also supported, so any relative URIs found in the document posted will be resolved against the value of the xml:base attribute.
Updating
POSTing an update to the metabox requires the full update capability.
The Content-Type header in the request must be application/vnd.talis.changeset+xml or
application/vnd.talis.changeset+turtle indicating that the request contains a Changeset.
By default, any blank nodes in RDF added to the metabox via POST are replaced with generated URIs. Any relative URIs will also be replaced with generated URIs (of the formhttp://api.talis.com/stores/{storename}/items/{relative URI}). Use of xml:base is also supported, so any relative URIs found in the document posted will be resolved against the value of the xml:base attribute.
Batch Updating
Batch updating is carried out using a changeset batch.
A changeset batch is a single rdf document containing multiple changesets, for example
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"xmlns:cs="http://purl.org/vocab/changeset/schema#">
<rdf:Description rdf:about="http://example.com/changeset/1">
<rdf:type rdf:resource="http://purl.org/vocab/changeset/schema#ChangeSet" />
<cs:subjectOfChange rdf:nodeID="A0" />
<cs:creatorName>Talis</cs:creatorName>
<cs:changeReason>Change Happens</cs:changeReason>
<cs:addition>
<rdf:Statement>
<rdf:subject rdf:nodeID="A0" />
<rdf:predicate rdf:resource="http://example.com/schema#prop1" />
<rdf:object>A property value</rdf:object>
</rdf:Statement>
</cs:addition>
</rdf:Description>
<rdf:Description rdf:about="http://example.com/changeset/2">
<rdf:type rdf:resource="http://purl.org/vocab/changeset/schema#ChangeSet" />
<cs:subjectOfChange rdf:nodeID="A1" />
<cs:creatorName>Talis</cs:creatorName>
<cs:changeReason>Change Happens</cs:changeReason>
<cs:addition>
<rdf:Statement>
<rdf:subject rdf:nodeID="A1" />
<rdf:predicate rdf:resource="http://example.com/schema#prop1" />
<rdf:object>Another property value</rdf:object>
</rdf:Statement>
</cs:addition>
</rdf:Description>
</rdf:RDF>As before, with single changesets, the batch should be posted with the content type application/vnd.talis.changeset+xml.
Batches of changesets can contain changesets about different subjects, as shown above. They can also contain multiple changesets relating to the same subject. For this to be valid an order in which the changesets need to be applied to the subject needs to be defined. This is done using the preceding changeset property. Here is an example of a batch containing two changesets about the same subject linked using the preceding changeset property.
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:cs="http://purl.org/vocab/changeset/schema#" >
<rdf:Description rdf:about="http://api.talis.test/res/one/1">
<rdf:type rdf:resource="http://purl.org/vocab/changeset/schema#ChangeSet"/>
<cs:precedingChangeSet rdf:resource="http://api.talis.test/res/one/2" />
<cs:subjectOfChange rdf:resource="http://example.com/one"/>
<cs:creatorName>Talis</cs:creatorName>
<cs:changeReason>Change is inevitable</cs:changeReason>
<cs:removal rdf:resource="http://api.talis.test/res/one/1/removal/1"/>
<cs:addition rdf:resource="http://api.talis.test/res/one/1/addition/1"/>
</rdf:Description>
<rdf:Description rdf:about="http://api.talis.test/res/one/1/removal/1">
<rdf:type rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#Statement"/>
<rdf:subject rdf:resource="http://example.com/one"/>
<rdf:predicate rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
<rdf:object>Modified Label One</rdf:object>
</rdf:Description>
<rdf:Description rdf:about="http://api.talis.test/res/one/1/addition/1">
<rdf:type rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#Statement"/>
<rdf:subject rdf:resource="http://example.com/one"/>
<rdf:predicate rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
<rdf:object>Again Modified Label One</rdf:object>
</rdf:Description>
<rdf:Description rdf:about="http://api.talis.test/res/one/2">
<rdf:type rdf:resource="http://purl.org/vocab/changeset/schema#ChangeSet"/>
<cs:subjectOfChange rdf:resource="http://example.com/one"/>
<cs:creatorName>Talis</cs:creatorName>
<cs:changeReason>Change Happens</cs:changeReason>
<cs:removal rdf:resource="http://api.talis.test/res/one/2/removal/1"/>
<cs:addition rdf:resource="http://api.talis.test/res/one/2/addition/1"/>
</rdf:Description>
<rdf:Description rdf:about="http://api.talis.test/res/one/2/removal/1">
<rdf:type rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#Statement"/>
<rdf:subject rdf:resource="http://example.com/one"/>
<rdf:predicate rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
<rdf:object>Label One</rdf:object>
</rdf:Description>
<rdf:Description rdf:about="http://api.talis.test/res/one/2/addition/1">
<rdf:type rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#Statement"/>
<rdf:subject rdf:resource="http://example.com/one"/>
<rdf:predicate rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
<rdf:object>Modified Label One</rdf:object>
</rdf:Description>
</rdf:RDF>
If a batch contains changesets about the same subject which are not linked in a valid single list using the preceding changeset property the batch will be rejected.
Processing of Requests
Batches are atomic - if any changeset within the batch can not be applied - none of the changesets with the batch will be applied - they will all be rejected.
Ideally, there should be no difference between submitting a single changeset and a batch. Where possible, the Platform will aim to process changesets synchronously and (where successful) return a 200/201 response (depending on whether the request was made to the versioned or unversioned URI). In reality though, there may significant variance in the overhead of processing a request, according to several factors.
Firstly, it is reasonable to assume that processing a request representing a batch of many thousands of changesets will consume more resources than one containing a single changeset. Also, the degree to which the changesets within a request are linked, whether the changesets themselves are to be persisted (i.e. versioned update), whether other, the existence of previous changesets relating to the changeset(s) subject of change, the size of the underlying store, the size of the individual changeset(s) and contention on the server side due to load may all affect the processing.
The Platform will endeavor to process requests as quickly and efficiently as possible, meaning that in cases where the server determines that it can apply the received changesets in a timely fashion, it will do so and return a 200 or 201 response.
Status Codes
Where the Platform is able to process the request synchronously, the status code will be 200 for unversioned updates, and 201 for versioned updates. Clients may assume that all updates have been successfully processed. In cases where the request is deemed too expensive to process synchronously, the response will have a 202 status, and the client should not assume that the changeset(s) have been completely processed yet.
Response Headers
Requests containing a single changeset will always include a Link header containing the uri of the changeset's subject of change. In addition, a custom "CHANGESET_SUBJECT" header will be returned with the same value. This non-standard header is purely for backwards compatibility and should be considered deprecated.
For versioned update requests containing a single changeset, an additional Location header will be returned, containing the uri assigned to the changeset itself.
Requests containing multiple changesets (whether versioned or unversioned) will not include these headers. See below for details of how the subject of change and changeset uris can be extracted from the entity body of these responses.
In future releases, any response with a 202 status (whether versioned/unversioned, single/multiple changesets) may also contain an additional Link header (with the value of the "rel" attribute to be specified). This header will contain a URI which will dereference to a representation of the status of the update. This models a receipt or log of the update and will allow clients to determine its progress.
Response Entity Body
For requests containing a single changeset, the entity body of the response will contain the changeset as it was applied (with any bnodes replaced by generated uris, and any added triples - such as those detailing the datestamp etc - included).
For requests containing multiple changesets, the entity body will contain an rdf document mapping the uris of changesets in the request to their subject of change as at application. So, if a request contains multiple changesets with bnodes as subject of change (implying the creation of new resources), it is important that the changesets themselves are named resources, so that the mapping document can be generated.
Determining the cost of request
As mentioned above, there are numerous factors which may affect the Platform's ability to process a request synchronously. Over time, we intend to extend realtime monitoring to enable more of these factors to be taken into account when deciding whether to process a changeset request immediately. However, in the first case, we plan to use the blunt heuristic detailed here:
If a request contains fewer than 15 changesets, it will be processed synchronously - returning a 200/201 status - UNLESS the total size in bytes of the request exceeds a set limit (see below).
All update requests (versioned/unversioned/single changeset/multiple changesets) are subject to a maximum size. Currently, this threshold is set to 5,242,880 bytes (5MB), though this may change at a later date. Any request which exceeds this limit will result in a 413 response, and none of its updates will be processed.
© Talis Systems Ltd. 2011 Content is available under