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: }
Get a copy job status (finished). 
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": "done"
S: }
The copy job may get deleted by the service after any time after completion but it is recommended to keep it for enough time for the client to check back.

Finalise a copy operation

Finalize a copy operation. Can only be executed on research objects in transient state, created as a result of a (not finalized) copy operation.

The finalisation operation may take a considerable amount of time because it may involve verifying the research object quality. For that reason it is realised in a form of a job that can be created and monitored by the client. 

C: POST http://example.com/evo/finalize/ HTTP/1.1
C: Content-Type: application/json
C: Authorization: Bearer 47d5423c-b507-4e1c-7
C:
C: { 
C:   "target": "http://example.com/ROs/copy-1/",
C: }

S: HTTP/1.1 201 Created
S: Location: http://example.com/evo/finalize/345
Getting a status of a successfully finished finalization. 
C: GET http://example.com/evo/finalize/345 HTTP/1.1
C: Accept: application/json

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S:
S: {
S:   "target": "http://example.com/ROs/copy-1/",
S:   "status": "done"
S: }
The finalization may perform additional verification of the research object depending on the intended status. If the verification fails, the service will answer with a status failed and an explanation in reason. 
C: GET http://example.com/evo/finalize/345 HTTP/1.1
C: Accept: application/json

S: HTTP/1.1 200 OK
S: Content-Type: application/json
S:
S: {
S:   "target": "http://example.com/ROs/copy-1/",
S:   "status": "failed",
S:   "reason": "Please annotate foo/bar.txt"
S: }

Cancel a copy operation

In order to cancel the copy operation after the copying finished but before it was finalized, the client must simply delete the transient research object. 

C: DELETE http://example.com/ROs/copy-1/ HTTP/1.1

S: HTTP/1.1 204 No Content

Get evolution information of RO

A separate but linked resource can be used to query for evolution information of a research object. The resource URI is obtained via a link relation returned when querying the RO itself.

@@ Option to include this link in the RO manifest?

An example for a Live RO. 

C: HEAD http://example.com/ROs/ro-id/ HTTP/1.1

S: HTTP/1.1 200 OK
S: Content-Type: application/rdf+xml
S: Link: <http://example.com/evo/info?ro=/ROs/ro-id/>;rel="ro:roevo-info"

C: GET http://example.com/evo/info?ro=/ROs/ro-id/ HTTP/1.1
C: Accept: text/turtle

S: HTTP/1.1 200 OK
S: Content-Type: text/turtle
S:
S: @prefix roevo: <http://purl.org/wf4ever/roevo#> .
S: @prefix prov: <http://www.w3.org/ns/prov#> .
S:
S: <http://example.com/ROs/ro-id/> a roevo:LiveRO;
S:        roevo:hasSnapshot <http://example.com/ROs/ro-id/roevo/copy-1/> ;
S:        prov:hadOriginalSource <http://www.myexperiment.org/packs/258> .
S:
S: <http://example.com/ROs/ro-id/roevo/copy-1> roevo:snapshotedAtTime "2012-05-07T09:18:48.056Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
An example for a Snapshot RO. 
C: HEAD http://example.com/ROs/copy-1/ HTTP/1.1

S: HTTP/1.1 200 OK
S: Content-Type: application/rdf+xml
S: Link: <http://example.com/evo/info?ro=/ROs/copy-1/>;rel="ro:roevo-info"

C: GET http://example.com/evo/info?ro=/ROs/copy-1/ HTTP/1.1
C: Accept: text/turtle

S: HTTP/1.1 200 OK
S: Content-Type: text/turtle
S:
S: @prefix roevo: <http://purl.org/wf4ever/roevo#> .
S: @prefix prov: <http://www.w3.org/ns/prov#> .
S: @prefix dcterms: <http://purl.org/dc/terms/> .
S:
S: <http://example.com/ROs/ro-id/roevo/copy-1/> a roevo:SnapshotRO;
S:        roevo:isSnapshotOf <http://example.com/ROs/ro-id/> ;
S:        roevo:snapshotedAtTime "2012-05-07T09:18:48.056Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
✅ Notes
  • Getting evolution information of an RO in transient state is not allowed?
  • Copies are not having all the evolution information, such as previousVersion. Only a link to the RO from which it was copied, is kept.

Link relations

From the service description, the client may use the following links to find the service resources:

The URI template is is used to construct a resource URI by:
  • applying the URI template expansion procedures with caller-supplied RO URI (for the evolution information resource)
  • resolving the resulting URI-reference to an absolute URI using normal URI resolution rules (e.g. typically, using the *service document URI as a base URI)
See also:

Resources and formats

Service description

The evolution service description is an RDF file that contains URI templates for accessing RO evolution related services. The RDF syntax used may be content negotiated. In the absence of content negotiation, RDF/XML should be returned. 

@prefix evo: <http://purl.org/ro/service/evolution/> .

. evo:copy "http://example.com/evo/copy/" ;
   evo:finalize "http://example.com/evo/finalize/" ;
   evo:info "http://example.com/evo/info{?ro}" .

Copy resource

The commands to copy a research object use a JSON object to store the operation parameters. JSON schema:

  • copyfrom: URI of the research object that will be copied.
  • type: Type of the new research object. Allowed values are "live", "SNAPSHOT", "ARCHIVE".
  • deepcopy: aggregated resources that should be copied with their content. Default is "uri-prefix": ["ro_URI"], where ro_URI is the URI of the copyfrom research object, which resolves to all resources that have the RO URI as their prefix.
    • uri-list: a list of URIs of aggregated resources
    • uri-prefix: a list of URI prefixes of aggregated resources
  • finalize: True if the service should perform a finalization of the copy operation, false otherwise. The default value is false.
  • target: The URI of the new research object.
  • status: Copy job status. Allowed values are "running", "done", "failed" or "service_error".
  • reason: Reason for the job status.
The copyfrom and type MUST be provided by the client, and deepcopy and finalize MAY be provided by the client. target, status and reason are provided by the service.

Finalize resource

The commands to copy a research object use a JSON object to store the operation parameters. JSON schema:

  • target: URI of the transient research object that will be finalized.
  • status: Finalise job status. Allowed values are "running", "done", "failed" or "service_error".
  • reason: Reason for the job status.
The target MUST be provided by the client. status and reason are provided by the service.

Evolution information resource

The evolution information is an RDF graph using the RO evolution ontology.

Security considerations

It is assumed that the service implementing this API will share the authorization mechanism with the ROSR Service in which the copies are created.

References

RO evolution

To Be discussed

From the identification & Versioning page, would it be sensible the following approach for identification of ROs:

So, for instance, the following URIs would be used for the MetabolicRO:

http://sandbox.wf4ever-project.org/rosrs5/ROs/MetabolicRO/ (points to the Live RO) - That is, by default, we work with a live RO (as it is now, so it is compatible with the existing ROSR API)

Live RO

http://sandbox.wf4ever-project.org/rosrs5/ROs/MetabolicRO/Live/

Snapshot ROs

http://sandbox.wf4ever-project.org/rosrs5/ROs/MetabolicRO/Snapshot/1.0/ (first version)

http://sandbox.wf4ever-project.org/rosrs5/ROs/MetabolicRO/Snapshot/1.2/ (minor change)

http://sandbox.wf4ever-project.org/rosrs5/ROs/MetabolicRO/Snapshot/1.5/ (minor change)

http://sandbox.wf4ever-project.org/rosrs5/ROs/MetabolicRO/Snapshot/2.0/ (major change & current version)

http://sandbox.wf4ever-project.org/rosrs5/ROs/MetabolicRO/Snapshot/ (research object snapshot series; point the same as previous)

Archived RO

http://sandbox.wf4ever-project.org/rosrs5/ROs/MetabolicRO/Archived/

Add a custom footer

RO Services and APIs

Clone this wiki locally