In order to merge the "sesame native" and "stardog remote" branches we are proposing to define a protocol for the drafter API which can be implemented for different backends. Initially it will be specific to the functionality required by the drafter server, however drafter client defines various protocols for drafter functionality so eventually the goal is to merge these into a single drafter.protocols
library which both will implement as required.
Drafter is currently tied quite heavily to the sesame repository API so another goal of the modular backend is to move this explicit dependency into the sesame-specific backend(s).
There are two main parts to the API - the various SPARQL endpoints (raw, live, draft, state) and the 'job' functionality for creating, populating and publishing draft graphs.
Job API
Below are the proposed functions for the job API functions to add to the protocol
create-managed-graph
create-managed-graph(uri: URI, metadata: Map[String, String] = Map.empty): Unit
Defines a new managed graph in the state graph. This function already exists in the drafter client.
create-draft-graph
create-graft-graph(live-uri: URI, metadata: Map[String, String] = Map.empty): URI
This function exists in the drafter client however the drafter server version expects the live-uri
to already exist as a managed graph while the client documentation does not specify this restriction.
migrate-graph-to-live
def migrate-graphs-to-live(draftGraphs: Seq[URI]): Job
Migrates a collection of draft graphs to live. Note the implementation of this function in the sesame native
and stardog-remote
branches are quite different.
delete-graph
def deleteGraph(graphUri: URI, contentsOnly: Boolean = false): Job
Deletes a managed graph and optionally its entry in the state graph. This is called drop-graph
in the drafter client protocols but it is not yet implemented there.
append-data-to-graph-job
append-data-to-graph-job(graphUri: URI, statements: Seq[Statement], metadata: Map[String, String] = Map.empty): Job
Appends the given data and optional metadata to a managed graph. Called append-data!
in drafter client.
update-metadata
updateMetadata(graphs: Seq[URI], metadata: Map[String, String]): Unit
Updates the metadata associated with a collection of managed graphs. Called assoc-metadata
in drafter client although that only allows a single graph to be specified.
delete-metadata
delete-metadata(graph: Seq[URI], metaKeys: Seq[String]): Unit
Deletes the named metadata keys associated with a collection of managed graphs. Called dissoc-metadata
in drafter client although that only allows a single graph to be specified.
SPARQL API
The SPARQL API should be separated from the Sesame Repository API.
update-restricted
update-restricted(query: String, restrictions: Set[URI] = Set.empty): Unit
Submit an update statement with a given graph restriction.
Querying
The query API currently makes reference to various concrete sesame repository types to do content negotiation. Initially this dependency could be broken by providing three functions in the query API:
def prepareQuery(query: String, restrictions: Set[URI]): TPrep
def getQueryType(preparedQuery: TPrep): QueryType
def getResultStreamer(query: TPrep, format: ResultFormat): (OutputStream => ())
where QueryType
indicates whether the query is an ASK
CONSTRUCT
or SELECT
query.