Versioning the graph and api

[ThomasThelen]

On the Jan 27'th salmantics call we brought up the idea of versioning the graph and creating a set of API endpoints that are also versioned.

Versioned Graph

Virtuoso doesn't support versions the same way that GraphDB does. Instead of creating new repositories, subgraphs are used.

Graph Version URI (subgraph URI)

Each subgraph name should follow a convention that we define here. We should use the full slinky URI followed by the version.

For example,

1. https://api.test.dataone.org/slinky/v1 --> Version 1
2. https://api.test.dataone.org/slinky/v2 --> Version 2

Example: Query V1 Graph

The SPAQRL query is sent to https://api.test.dataone.org/slinky/query to ask for triples in the https://api.test.dataone.org/slinky/v1 graph.

SELECT * WHERE {
    GRAPH <https://api.test.dataone.org/slinky/v1/> {
        ?dataset rdf:type schema:Dataset .
        ?dataset schema:name ?name .
        ?dataset schema:creator ?creator .
        OPTIONAL {?dataset schema:description ?description . }
  }
}

Query V2 Graph

The SPAQRL query is sent to https://api.test.dataone.org/slinky/query to ask for triples in the https://api.test.dataone.org/slinky/v2 graph.

SELECT * WHERE {
    GRAPH <https://api.test.dataone.org/slinky/v2/> {
        ?dataset rdf:type schema:Dataset .
        ?dataset schema:name ?name .
        ?dataset schema:creator ?creator .
        OPTIONAL {?dataset schema:description ?description . }
  }
}

Associated Tasks

• Extend Slinky to write to named graphs
• Update the frontend to match the GRAPH SPARQL pattern

Versioned API Endpoints

On the same Jan 27th call it was decided that we want a number of utility endpoints:

• /datasets/<dataset_pid>
• /persons/<dataset_pid>&<person_name>&<person_id>
• /organizations/<org_name>&<org_id>
• /iri/

Since each one of these will involve a SPARQL query that we construct on the backend, we have complete control over the SPARQL query. This allows us to insert the version based on content from the URL.

For example, the following endpoint URLs query v1 of the graph

1. https://api.test.dataone.org/slinky/v1/datasets
2. https://api.test.dataone.org/slinky/v1/persons

The version 2 analogues,
https://api.test.dataone.org/slinky/v2/datasets
https://api.test.dataone.org/slinky/v2/persons

Associated Tasks

• Determine what each endpoint does
• Create the endpoints in slinky
• Expose an OpenAPI endpoint page