Using GRIP

philipfennell edited this page Feb 1, 2012 · 13 revisions

##Introduction

GRIP supports the W3C's SPARQL 1.1 Graph Store HTTP Protocol which:

describes updating and fetching RDF graph content from a Graph Store over HTTP in the REST style. In doing so, it appeals to the following interface constraints that comprise the REST architectural style:

  1. identification of resources
  2. manipulation of resources through representations
  3. self-descriptive messages

GRIP serves its requests through a RESTful framework, which is itself in development and may ultimately become a project on GitHub in due course, that utilises the facilities of MarkLogic and XQuery along with XSLT for entity and resource representation transformations.

##Storing RDF Graphs

When graphs are submitted to the store, GRIP transforms them into an internal representation that is efficient for storage and querying. Given the variety of RDF graph representations a design choice was made to use an intermediate XML format that ensures a common interface between the storage and the service layers. XML was chosen, in the context of MarkLogic, as it is by far the easiest, and most efficient, way to apply transformations to/from other formats. The XML format was created by Jeremy J. Carroll and Patrick Stickler and is called TriX: RDF Triples in XML and, put simply, is an XML representation of RDF triples with the addition of the ability to specify a graph URI (named graph)

The actual internal, storage, representation is defined in the markLogic/semantic web page. As efficient as this format is, it was necessary to extend this format to ensure that language and type information was persisted during graph storage so that graphs could be effectively round-tripped through the store. In addition, for each graph that has its triples persisted in the database a 'graph' document is created that stored metadata about the graph including the namespaces (and their prefixes) that we used on the incoming graph representation.

GRIP will, currently, allow you to submit graphs in RDF/XML, TriX and N-Triples and also retrieve them in any of those representations:

RDF/XML      application/rdf+xml    .rdf
TriX         application/xml        .xml
N-Triples    plain/text             .nt

##Managing Graphs

The Graph Store HTTP Protocol defines a set of operations, or actions that can be performed against a store. You can reference graphs either directly, or indirectly.

###Direct Graph Identification

GRIP supports the ability to create a specific graph URI that can be dereferenced to obtain a representation of the graph content. By default, the base URI for the Graph Store Service is:

http://localhost:8005/graphs

and this URI should be regarded as the 'collection' of graphs stored by the service. Thus, submitting an HTTP POST request with an RDF Graph document in the body of the request:

POST /graphs HTTP/1.1
Host: localhost:8005
Slug: "direct graph test"
Content-Type: application/rdf+xml
... RDF payload ...    

will result in the graph being stored in the database against a URI created from the base URI plus the value of the 'Slug' header. The Slug header is used by the Atom Publishing Protocol for defining a human readable title for a new resource that can also be used in creating its URI.

The response from such a request would be:

HTTP/1.1 201 Created
Server:  MarkLogic
Location: http://localhost:8005/graphs/direct-graph-test

GET requests to the URI returned in the Location header will retrieve a representation of the graph in the chosen format according to the requests Accept header or file extension if you're not in control of the Accept header (not so RESTful but decidedly practical given the way browsers are, still, these days). Plug-ins like Poster or Modify Headers for Firefox or Chrome's REST Console are handy for solving this problem. The default representation in RDF/XML.

Subsequent POSTs to the same URI will 'merge' any new triples with those already there in the identified graph. PUTs will replace the triples in the identified graph and a DELETE request will remove the graph completely from the store.

###Indirect Graph Identification

...