Metabox

From n² wiki

Nearby: Platform API, Metabox Changesets Collection

URI Pattern

http://api.talis.com/stores/{store}/meta

Allowed Methods

GET, POST

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

Contents 1 GET 2 POST 3 Batch Changesets 3.1 Processing of Requests 3.2 Status Codes 3.3 Response Headers 3.4 Response Entity Body 3.5 Determining the cost of request

[edit] GET

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 application/turtle

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.

[edit] POST

POSTing to the metabox requires the full update capability.

The behaviour of a POST request depends on its content-type header:

application/rdf+xml

The body of the post is treated as RDF that should be merged/added to the metabox.

application/vnd.talis.changeset+xml

The body of the post is treated as a Changeset document that should be applied to the metabox.

By default, any blank nodes in RDF added to the metabox via POST are replaced with generated URIs. Additionally all URIs must be absolute since no base URI can be specified outside of the body of the request. Use of xml:base is supported.

[edit] Batch Changesets

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.

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

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

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

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

[edit] 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 2097152 bytes (2MB), 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.