Skip to content

RO evolution API

Jump to bottom Edit New page
Soumya Brahma edited this page Feb 4, 2016 · 21 revisions

Table of Contents

Goals

The goals of this API are:

  • Enable the creation of different types ROs (Live, Snapshot, Archived)
  • Mechanism to "clone" an RO from an internal RO, external RO resource, external non-RO content.
  • Retrieve the evolution provenance of an RO, including the direct evolution (e.g., priorVersion) and contributions (e.g., derivedFrom, originalSource, etc.)
  • Retrieve list of snapshots, archived ROs.

Requirements

This API should:

  • Vocabulary for describing RO evolution, including RO types and relations: roevo
  • Special creation operation of an RO, which makes a copy from another resource
  • Handle different types of ROs, representing different stages in its lifecycle
  • Handle RO versions
  • Handle relations with other resources (e.g., contributions)
  • Prevent modification of snapshots and archived ROs

API function overview

The goals of this API are to enable transformation of the research objects based on their lifecycle and to facilitate retrieving the evolution history of the research objects.

The lifecycle transformation of research objects is achieved by providing a service that performs a copy of a research object and saves the copy as a live, snapshot or archived research object. The client needs to make two requests to complete the copying:

  • Copy a research object. The new research object is in a transient state and is available only to the creator. It can still be modified before reaching the target evolution state.
  • Finalize the state transformation. The service validates that the transient research object meets the requirements for being in the target evolution state and performs the state transition. For evolution states such as a snapshot or archived research object, that means that the research object becomes immutable.
The first and second requests can be combined into one if the client does not intend to modify the copy before finalizing the transformation.

The second API functionality is a facility for retrieving the evolution provenance. The client may send a request with a research object URI as a query parameter and the service will return an RDF graph with selected information about the research object in question, its copies and the research object that it itself was copied from. Note that typically this information can equally be achieved with a series of SPARQL queries to the ROSR service hosting the research object.

The service is based on the research object evolution model.

API Usage

❗ URIs here are all examples - not fixed by API

⚠️ Piotr 

At this moment I would suggest that the URIs for all types of ROs have the same format and leave introducing special URI forms for a second step.

If a client wants to create a copy of an RO (i.e. a snapshot), the steps are:

  1. Retrieve the evolution service document and find the links to copy and finalize resources
  2. Create a new copy job and wait until it finishes
  3. Modify the copy in any way, i.e. delete temporary or private resources.
  4. Create a new finalize job and wait until it finishes
To check the evolution provenance of an RO, the steps are:
  1. Perform a GET or HEAD operation to the RO to find the link to evolution information resource
  2. Retrieve the evolution provenance information using the link provided

Retrieve the service document

The client retrieves the service document to learn the URI templates for the resources. 

C: GET http://example.com/evo/ HTTP/1.1
C: Accept: text/turtle

S: HTTP/1.1 200 OK
S: Content-Type: text/turtle
S:
S: @prefix evo: <http://purl.org/ro/service/evolution/> .
S:
S: . evo:copy "http://example.com/evo/copy/" ;
S:    evo:finalize "http://example.com/evo/finalize/" ;
S:    evo:info "http://example.com/evo/info{?ro}" .

Create an RO copy

This operation creates a copy of a research object. The new research object is in a transient state unless the operation is immediately finalised. Transient state means it is only available to the creator. The type of the copy has to be defined because it influences the new research object URI form.

A "Slug" HTTP header may be used to indicate the requested RO id.

Creating and finalising a copy may be presented to the user as one operation, only the client application will use a one step or two step process.

Copyfrom URI may be a research object in the same ROSR service, a research object in another ROSR service, or even an external non-RO content. It is more an implementation detail how the copy will be made in each of these cases.

The copy operation may take a considerable amount of time because it may involve copying resource contents. For that reason it is realised in a form of a job that can be created and monitored by the client.

⚠️ Define the copy manifest changes 

We should define which fields from the manifest are copied and which are added. For example, the dcterms:creator will probably be copied but evo:asSnapshotedBy or similar will be used for the person who made the copy.
Initiate a copy job. 
C: POST http://example.com/evo/copy/ HTTP/1.1
C: Content-Type: application/json
C: Authorization: Bearer 47d5423c-b507-4e1c-7
C: Slug: copy-1
C:
C: { 
C:   "copyfrom": "http://example.com/ROs/ro-id/",
C:   "type": "SNAPSHOT",
C:   "finalize": false
C: }

S: HTTP/1.1 201 Created
S: Location: http://example.com/evo/copy/12345
S:
S: {
S:   "copyfrom": "http://example.com/ROs/ro-id/",
S:   "type": "SNAPSHOT",
S:   "finalize": false,
S:   "target": "http://example.com/ROs/copy-1/",
S:   "status": "running"
S: }
Get a copy job status (running). 
C: GET http://example.com/evo/copy/12345 HTTP/1.1
C: Accept: application/json

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S:
S: {
S:   "copyfrom": "http://example.com/ROs/ro-id/",
S:   "type": "SNAPSHOT",
S:   "finalize": false,
S:   "target": "http://example.com/ROs/copy-1/",
S:   "status": "running"
S: }
Add a custom footer

RO Services and APIs

Clone this wiki locally