Skip to content

Stability Evaluation API

Jump to bottom Edit New page
Soumya Brahma edited this page Feb 6, 2016 · 19 revisions

Table of Contents

API function overview

The stability measurement consists on the evaluation of the RO along time. The idea is to capture concrete values provided by the evaluation of the RO in different moments of its evolution. In other words, by subjecting the snapshots of a RO to the checklist evaluation (that may vary its purpose). This API will provide a global evaluation of the stability of the RO that is evaluated and a list of measurements that correspond to the snapshots of the RO. The RO that we want to measure, the minim and the purpose will be needed as inputs.

API usage

As the usage of this API is very similar to the checklist evaluation service, and some of the concepts are reused from there, it's recommended to take a look to the checklist API for additional information.

Let's suppose that we have available this different set of resources:

Those will be the inputs needed for calling the webservice, as we can see in the following explanation:

The stability evaluation would then be invoked in a sequence of two HTTP operations:

  • Client retrieves service document:
C: GET /stability/rest/getStability HTTP/1.1
C: Host: service.example.org
C: Accept: application/rdf+xml
S: HTTP/1.1 200 OK
S: Content-Type: application/rdf+xml
S:
S: <?xml version="1.0"?>
S: <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
S: xmlns:roe="http://purl.org/ro/service/evaluate/stability">
S: <rdf:Description rdf:about="">
S: <roe:stability>/stability/rest/getStability{?RO,minim,purpose}</roe:stability>
S: </rdf:Description>
S: </rdf:RDF>
  • Client parses the service document, extracts the URI template for the checklist evaluation service and assembles URI for the desired evaluation result , and issues a second HTTP GET request: 
C: GET /stability/rest/getStability?RO=http://www.ro-examples.com/ro/fakeRO &minim=/minim/Repeatability.rdf &purpose=Repeatable HTTP/1.1
C: Host: service.example.org
C: Accept: application/json
S: HTTP/1.1 200 OK
S: Content-Type: application/json
S:
S: (result of the evaluation in json)
S:

Link relations

http://purl.org/ro/service/evaluate/stability

This relation is generally used used in the service description document

It indicates a relation between a service description and a URI template for RO evaluation results using the described service. The URI template is is used to construct a service result URI by:

  1. applying the URI template expansion procedures with caller-supplied RO URI, minim URI, purpose and
  2. 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:

HTTP methods

The only HTTP method available for this API is the GET method. Depending on the content negotiation (which is explained in the next point) we will get a)description of the servic or b)results obtained by the invocation of the stability evaluation.

Resources and resource formats

There are several responses that can be provided by the service depending on the type content negotiation. In absence of content negotiation we will get a service description in RDF. We can also negotiate the kind of response of the service with the corresponding parameters in order to get the results in XML or in JSON.

Service description 

 <?xml version="1.0" ?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:roe="http://purl.org/ro/service/evaluate/stability">
  <rdf:Description rdf:about="">
    <roe:stability>
      /stability/rest/getStability{?RO,minim,purpose}
    </roe:stability>
  </rdf:Description>
</rdf:RDF>

Outputs of the stability evaluation

In this section we will explain not only the different kinds of outputs but also the meaning of them. In the examples we will find the following concepts for describing the results:

  • ro: the RO that has been evaluated (uri)
  • stabilityValue: the main result of the API, the stability value (double between 0 and 1 that reflects the standard deviation of the checklist evaluation values).
  • listElements: list of measured snapshots of the RO
    • uri: uri of the snapshot (uri)
    • value: result obtained by the evaluation the snapshot using the checklist (double between 0 and 1 that shows the percentage of requirements that have been satisfied)
    • date: date of the snapshot (DD/MM/YYYY)
Some information additional information:

JSON

Provisional json Output example: 

 {
  "ro":"http://www.ro-examples.com/ro/fakeRO",
  "stabilityValue":"0.8105506067403516",
  "listElements":[
    {
      "uri":"http://www.ro-examples.com/ro/fakeROSnapshot1",
      "value":"0.11102273035109067",
      "date":"14/06/2012"
    },
    {
      "uri":"http://www.ro-examples.com/ro/fakeROSnapshot2",
      "value":"0.06829956253911362",
      "date":"17/06/2012"
    },
    {
      "uri":"http://www.ro-examples.com/ro/fakeROSnapshot1",
      "value":"0.4898372013610631",
      "date":"20/06/2012"
    }
  ]
}

XML

Provisional xml Output example: 

<?xml version="1.0" encoding="UTF-8"?>
<itemStability>
   <ro>http://www.ro-examples.com/ro/fakeRO</ro>
   <stabilityValue>0.9351577967137268</stabilityValue>
   <listElements>
      <uri>http://www.ro-examples.com/ro/fakeROSnapshot1</uri>
      <value>1.0</value>
      <date>19/06/2012</date>
   </listElements>
   <listElements>
      <uri>http://www.ro-examples.com/ro/fakeROSnapshot2</uri>
      <value>0.8888888888888888</value>
      <date>19/06/2012</date>
   </listElements>
   <listElements>
      <uri>http://www.ro-examples.com/ro/fakeROSnapshot3</uri>
      <value>0.8461538461538461</value>
      <date>19/06/2012</date>
   </listElements>
</itemStability>

Security considerations

Stability evaluation is a read-only function, so there shouldn't be any security risks of adding or deleting content. The main problem is that this service provides information about the RO and its snapshots, and the person who is going to see the results of the service should have access permissions to it.

Cache considerations

Stability measurement is not supposed to change often, so it seems a good idea to have some control in order to avoid excessive use of the service and keep it efficient.

If we are calling the stability evaluation service two or more times in a row we will probably get the same results each time (unless we change the minim or the purpose of the checklist), so it is not necessary to recalculate everything.

TODO: add link

References

  1. This API is part of the showcase 68
  2. Is strongly related with the checklist evaluation
  3. And uses the work of RO evolution
  4. Research Object:

Feedback/comments by GK (remove this section later)

Aleix,

I think you're on the right lines here, but there are a few areas that might need clarifying a little.

Overview / usage

What is the time period over which stability is evaluated; how is it determined? Maybe some additional (optional) template parameters would be appropriate?

I see your notion of stability is closely related to a particular minim-based checklist - roughly you measure the stability of an RO with respect to a particular checklist? If so, it might be sufficient to reference the corresponding checklist API and simply say the paramneters are as defined there. (You don't mention target, but maybe it makes sense that stability is only meaningful with respect to a complete RO?)

I think what's important to capture here is a sense of how a checklist evaluation may change over time, and how that determines a notion of stability.

I would expect the URI template to appear in a service document, probably with its own link relation, so that the usage would cover the essential steps; e.g.

Srtarting with service URI, RO to evaluate, checklist details:

  1. Retrieve service document
  2. Extract the stability evaluation link and usethe resulting value as a URI template...
  3. Retrieve evaluation result using constructed URI
I think this pattern would almost identical to the checklist API, except that a different link relation is used, and (if additional parameters are used to define the time period for the evaluation) some additional values may be referenced by the template.

Nit: the example given shows an RO URI that has not been %-escaped. If the RO or Minim URI contain fragment identifiers, this would cause problems with URI interprtation. For this reason, in the Checklist API, I use the URI-template form

Unknown macro: {...} , which causes all URI-reserved characters to be %-escaped.

Link relation

You'll need a URI that relates the service document to the URI template for the stability evaluation result. Following the checklist pattern, I'd suggest:

But you can choose your own if you prefer.

No mention of HTTP methods

You only use GET: I think it's worth stating. This keeps things relatively simple, which is good.

It may be better to make the HTTP method conventions part of the resources descriptions (i.e. muy templkate may be sub-optimal) - we should see how this plays out with the RODL service APIs.

Resources and resource formats

There's no mention of Service Descripotion, which I think is needed. A principle of RESP APIs is that starting with just the URI of the service you can navigate links to find all the resources your application needs to access or manipulate. The service description is what you get when dereferencing the service URI - sometimes called an "API home page" or "Service document". (Other mechanisms are possible, e.g. HTTP Link header, but this seems easy enough in this case.)

You mention RO as a resource, but don't provide description or reference to what it is and possible formats. I suggest using links to the RO model pages.

You don't mention minim description as a resource (could just reference the checklist API description - doesn't need to be long)

The key resource that your API introduces is the stability evaluation result, which you do describe.

Security considerations

Looks good for now. Be prepared to expand on this as and when particular security/privacy threats are identified.

Cache considerations

What I'd try to focus on here is how the service interacts specifically with HTTP cacheing.

This is a topic that I introduced in the template because it's such a fundamental aspect of HTTP, and it is so easy to cause incorrectly cached values to be returned. But maybe this isn't something that should be part of every API description. Maybe we should (a) find a write-up on the web, or (b) add a one-off description of issues to the architecture document, then simply reference that?

References

Probably need references to RO.

Add a custom footer

RO Services and APIs

Clone this wiki locally