Platform Release 12 Notes

From n² wiki

Jump to: navigation, search

Contents

[edit] API-99 - Store Groups

It is possible to define groups of stores that behave as a single read-only unit. To create a group, someone with platform-config capability POSTs the rdf/xml description of the group to http://api.talis.com/groups 

 <rdf:Description>
   <bf:groupRef>ne-cons</bf:groupRef>
   <rdfs:label>North-east consortium</rdfs:label>
   <rdfs:comment>A group of stores from the northeast</rdfs:comment>
   <bf:store rdf:resource="http://api.talis.com/stores/store1" />
   <bf:store rdf:resource="http://api.talis.com/stores/store2" />
   <bf:store rdf:resource="http://api.talis.com/stores/store3" />
 </rdf:Description>

The above would create a store group called ne-cons, available at http://api.talis.com/groups/ne-cons

Initially the number of stores is limited to 5. Any attempt to create a group with more than 5 stores results in a 400 response. This limit may be removed later.

A user with basic-search capability in all the stores comprising the group is able to search all the items in all the stores by issuing a query like: http://api.talis.com/groups/ne-cons/items?query=foo

This search service supports all the parameters of a standard content box search except for the sort parameter. Accessing the URI without any query parameters returns an HTML form in the same way as the standard store contentbox.

A user with basic-search capability in all the stores comprising the group is able to search all the RDF in all the stores by issuing a query like: http://api.talis.com/groups/ne-cons/services/sparql?query=foo

This sparql service supports all the parameters of a standard sparql search. Accessing the URI without any query parameters returns a HTML form in the same way as the standard store sparql service.


[edit] API-99 - Batch Changesets

Up until now, only a single changeset per HTTP request could be submitted to the Platform. API-60 proposes that batches of changesets can be applied to the metabox, private graphs (both versioned and unversioned) and the Platform configuration.

Batches are posted to the following url's:

http://api.talis.com/stores/mystore/meta http://api.talis.com/stores/mystore/meta/changesets http://api.talis.com/stores/mystore/meta/graphs/graph1 http://api.talis.com/stores/mystore/meta/graphs/graph1/changesets http://api.talis.com/config

The 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 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.

[edit] API-176 - Unicode Characters Returned in Facet Results

This fixes a bug which corrupted unicode characters is results from the facet service.

[edit] Other Bug Fixes

Other bug fixes in this release include:

Retrieved from "http://n2.talis.com/wiki/Platform_Release_12_Notes"
Personal tools