Exploring Akka-HTTP in Scala (1)

Several months ago, while playing with Scala, I've experimented with Spray. As new needs for a production system have recently come up, I am looking at the natural descendent of Spray: Akka-HTTP.

The Akka-HTTP modules implement a full server- and client-side HTTP stack on top of akka-actors and akka-streams. It's not a web-framework but rather a more general toolkit for providing and consuming HTTP-based services. While interaction with a browser is of course also in scope it is not the primary focus of Akka HTTP.
From: Akka-HTTP

The simple need for a HTTP-service provider brought me to explore more of the interesting Akka ecosystem. In fact, Akka-HTTP promotes an interesting way of providing and consuming HTTP-based services and it is built on top of akka-actors and akka-streams.

Akka-actor system

Akka-actor implements the Actor Model to provide a better platform to build scalable, resilient and responsive applications.
From: What is Akka

Check out the following slides and see also the Reactive Manifesto and the Reactive Manifesto 2.0.

Introducing Akka from Jonas Bonér

Akka-streams

Akka-streams is an abstraction over the Actor system that simplify streams usage, for instance, by taking care of managing back-pressure.
From: Streams introduction

As Endre Varga put it in a very nice blog post (with simple and effective examples):

The primary goal of streams is to provide a simple way to:

• build concurrent and memory bounded computations
• that can safely interact with various forms of non-blocking IO interfaces
• without involving blocking
• while embracing multi-core concurrency,
• and solving the typical pitfall of missing back-pressure: faster producers overwhelm slower consumers that run on a separate thread, resulting in OutOfMemoryExceptions.

From: Threading & Concurrency in Akka Streams Explained (part I)

In the same post, Endre summarizes the properties of streams as:

• Streams do not run on the caller thread. Instead, they run on a different thread in the background, without blocking the caller. 
• Stream stages usually share the same thread unless they are explicitly demarcated from each other by an asynchronous boundary (which can be added by calling .async between the stages we want to separate). 
• Stages demarcated by asynchronous boundaries might run concurrently with each other. 
• Stages do not run on a dedicated thread, but they borrow one from a common pool for a short period.

Here is another good Akka-streams 101 and a presentation:

Reactive Stream Processing with Akka Streams from Konrad Malawski

Read about the more general initiative of Reactive Streams to provide a standard for asynchronous stream processing with non-blocking back pressure here. And see the following presentation:

NTS: JavaScript time and timezones... [1]

Coordinated Universal Time (UTC), is the primary time standard by which the world regulates clocks and time. It is, within about 1 second, mean solar time at 0° longitude;

UTC is one of several closely related successors to Greenwich Mean Time (GMT).

Greenwich Mean Time (GMT) is the mean solar time at the Royal Observatory in Greenwich, London.

UTC, while based on zero degrees longitude, which passes through the Greenwich Observatory, is based on atomic time and includes leap seconds as they are added to our clock every so often. UTC was used beginning in the mid-twentieth century but became the official standard of world time on January 1, 1972.

Although GMT and UTC share the same current time in practice, GMT is a time zone officially used in some European and African countries. UTC is not a time zone, but a time standard that is the basis for civil time and time zones worldwide. This means that no country or territory officially uses UTC as a local time.

Neither UTC nor GMT ever change for Daylight Saving Time (DST). However, some of the countries that use GMT switch to different time zones during their DST period.

The Eastern Time Zone (ET) is a time zone encompassing 17 U.S. states in the eastern part of the contiguous United States, parts of eastern Canada, the state of Quintana Roo in Mexico, Panama in Central America and the Caribbean Islands.

• Eastern Standard Time (EST) corresponds to ET standard time (autumn/winter) and it is 5 hours behind Coordinated Universal Time (UTC−05:00).
• Eastern Daylight Time (EDT), is used by some places when observing daylight saving time (spring/summer) is 4 hours behind Coordinated Universal Time (UTC−04:00).

Creating The Date object

There are four ways to create the Date object:

new Date()

We can create a JavaScript Date 'now' object as follows:

var d = new Date();

The Date is created with timezone set to the Local Time timezone (EST for me):

//  d -> Tue Jan 12 2016 23:34:03 GMT-0500 (EST)

It is then possible to compute the timezone difference between UTC and Local Time (EST):

var n = d.getTimezoneOffset();
//  n -> 300 (minutes, equivalent to 5 hours)

new Date(milliseconds)

JavaScript dates are calculated in milliseconds from 01 January, 1970 00:00:00 Universal Time (UTC).

var d = new Date(0); 
//  d -> Wed Dec 31 1969 19:00:00 GMT-0500 (EST) -> D1

One day contains 86,400,000 milliseconds.

var d = new Date(86400000); 
//  d -> Thu Jan 01 1970 19:00:00 GMT-0500 (EST)

By providing a negative amount of milliseconds we will refer to a date prior to 01 January, 1970 00:00:00 Universal Time (UTC).

var d = new Date(-86400000*365); 
//  d -> Tue Dec 31 1968 19:00:00 GMT-0500 (EST) -> One year prior to D1

new Date(dateString)

var d = new Date("October 12, 1973 11:13:00")); 
//  d -> Fri Oct 12 1973 11:13:00 GMT-0400 (EDT)

new Date(year, month, day, hours, minutes, seconds, milliseconds)

Note that the months are identified by 0-11 numbers. Where 0 is January.

var d = new Date(73,9,12,11,13,00,0);
//  d -> Fri Oct 12 1973 11:13:00 GMT-0400 (EDT)

Also note that when the year is specified with an integer between 0-99, that will be translated to a year between 1900 and 1999. In other words when the year is identified by the last or the last two digits (0 = 1900).

var d = new Date(0,9,12,11,13,00,0);
//  d -> Fri Oct 12 1900 11:13:00 GMT-0400 (EDT)

However, the year can be identified by four digits:

var d = new Date(1899,9,12,11,13,00,0);
//  d -> Thu Oct 12 1899 11:13:00 GMT-0400 (EDT)

So, in order to define a date with year between 0 and 99 we can use the method setFullYear():

var d = new Date(19,9,12,11,13,00,0);
d.setFullYear(19);
//  d -> Sat Oct 12 19 11:13:00 GMT-0400 (EDT)
//  d -> -61543010820000 (ms from 01 January, 1970 00:00:00 UTC)

Note that the method setYear() will behave exactly as the constructor:

var d = new Date(19,9,12,11,13,00,0);
d.setYear(19);
//  d -> Sun Oct 12 1919 11:13:00 GMT-0400 (EDT)
//  d -> -1584866820000 (ms from 01 January, 1970 00:00:00 UTC)

Read more on the Mozilla Developer Network.

NTS: JavaScript testing of null, undefined...

In JavaScript, there are a couple of ways to verify if a variable is not undefined.

Undefined

Undefined type is a built-in JavaScript type. undefined (immutable) value is a primitive and is the sole value of the Undefined type. Any property that has not been assigned a value, assumes the undefined value. A function without a return statement, or a function with an empty return statement returns undefined. The value of an unsupplied function argument is undefined. The undefined  global variable which is a reference to the value undefined. In ES3 this variable is mutable, while in ES5 it is immutable.

So the global undefined property represents the primitive value undefined.

Objects are aggregations of properties. A property can reference an object or a primitive. Primitives are values, they have no properties. In JavaScript there are 5 primitive types: undefined, null, boolean, string and number. Everything else is an object. The primitive types boolean, string and number can be wrapped by their object counterparts. These objects are instances of the Boolean, String and Number constructors respectively.

The latest ECMAScript standard defines seven data types (source Mozilla Contributors):

• Six data types that are primitives:
  • Boolean
  • Null
  • Undefined
  • Number
  • String
  • Symbol (new in ECMAScript 6)
• and https://developer.mozilla.org/en-US/docs/Glossary/Object

undefined is a a global variable or a property of the global object.

typeof undefined;  // "undefined"

var name = "Paolo Ciccarese";
name = undefined;
typeof name;       // "undefined"

From ES5 the property cannot be re-assigned, and an attempt will fail silently. By turning on the 'strict mode' attempting to assign a value to undefined will throw an error instead. In general, even when possible, re-assigning undefined is not a good idea.

The Global object is an intrinsic object whose purpose is to collect global functions and constants into one object. The global object itself can be accessed using the this operator in the global scope. The Global object cannot be created using the new operator. It is created when the scripting engine is initialized, thus making its functions and constants available immediately.

Undefined: Local or Declared Variables

if (name === undefined) ... // Works for local and/or declared variables

This approach (JSFiddle) works when the variable has been defined for instance in a function:

function myFunction(foo) {
    if (foo === undefined) {
        alert('sorry, that is undefined');
    }
}
myFunction();

However, if the variable has never been declared, that would trigger an exception (JSFiddle - see the console):

function myFunction() {
    if (foo === undefined) { // Triggers a ReferenceError exception
        alert('sorry, that is undefined');
    }
}
myFunction();

Therefore, this approach works well for local variables that we know have been declared. It is not a convenient approach for local variables that might have not been declared.

Avoid the following as it returns true also for null:

if (typeof foo == 'undefined') ... // Returns true also for null

Undefined: Global Variables

if(typeof name === "undefined") ... // Works for global and local variables

This approach works for both declared (JSFiddle):

function myFunction(foo) {
    if (typeof foo === 'undefined') {
        alert('sorry, that is undefined');
    }
}
myFunction();

and undeclared variables (JSFiddle):

function myFunction() {
    if (typeof foo === 'undefined') {
        alert('sorry, that is undefined');
    }
}
myFunction();

We might argue this last approach is safer in general.

Null

The Null (type) has exactly one value, called null (value). The value null is a JavaScript literal representing null or an "empty" value, i.e. no object value is present. It is one of JavaScript's primitive values and also - unlike undefined - a JavaScript keyword. Because of being a keyword, null is inherently unassignable, while ES5 had to add a special rule to cover the undefined global variable.

null is classified as a JavaScript Object:

typeof(null) // object
typeof(undefined) // undefined

The value null is a JavaScript literal representing null or an "empty" value, i.e. no object value is present. In other words we can assign null to a variable without a value:

var nv = null; // null
typeof nv      // object

Notice that:

null === undefined // false
null == undefined  // true*
null == false;     // false
null == '';        // false
null == 0;         // false

* see language specifications here

Testing for Null

So if we test with:

if (x == null) ... // Tests both null and undefined

We are actually testing for name to be null and undefined at the same time. But if we test with:

if (x === null) ... // Tests for null only

Testing for Undefined and Null

For testing both null and undefined (when a variable is declared) it is possible to do:

if (x != null)  ... // Tests both null and undefined

Ore more explicitly:

if (x !== undefined && x !== null)  ... // Tests both null and undefined

And to prevent ReferenceError for undeclared variables:

if (typeof x !== 'undefined' && x !== null)  ... // Tests null, undefined

Falsey values

In JavaScript we can also test with the following:

if (!x) ... // Tests for falsey values

Which will be evaluated true if name is: null, undefined, NaN, empty string ("" or ''), 0, -0, false. This checking has to be used carefully when the value of the data could be 0 or false or an empty string.

When SPARQL query length is an issue

While developing Annotopia I wrote some code to create dynamically SPARQL queries servicing a faceted search. According to the facets values, the queries can become extremely long... until I hit the limit:

Virtuoso 37000 Error SP031: SPARQL: Internal error: 
       The length of generated SQL text has exceeded 10000 lines of code

It seems that the SPARQL compiler stops because the SQL compiler, the successor in the processing pipeline, will fail to compile it in any reasonable time. After initial surprised reaction I started to dig deeper in the structure of my queries. Here is what I learned.

Use the FILTER + IN construct instead of multiple UNIONs

It might result simpler, when writing code, to dynamically compose a query with lists of UNIONs. Unfortunately that translates in much longer SQL queries. So this:

        
        { ?s oa:serializedBy <urn:application:domeo> }
        UNION
        { ?s oa:serializedBy <urn:application:utopia> }

for multiple items, should become:

        { ?s oa:serializedBy ?serializer .
            FILTER ( ?serializer IN 
               (<urn:application:domeo>, <urn:application:utopia>) )
        }

Annotopia 101 - Basic use for document/data annotation

This post explains how to get started in using Annotopia as a server for document/data annotation. It assumes Annotopia is already installed and running and that you have admin access to the instance.

Step 1. Register your system

After logging in (as admin) to Annotopia, you will see a welcome screen:

• Click on 'Administration Dashboard' (top left of the screen)

• Select 'Create System'

• Fill out the form and 'Save system'

• Take note of the 'API key' which is going to be used by your system to communicate with Annotopia when Annotopia is not set up to use a stronger Authentication mechanism.

 

Step 2. Create my first annotation (POST)

Assuming that the server address is http://myserver.example.com:8090 we are going to create our first POST. Normally your application will connect to the server through Ajax or a server call. For the sake of this tutorial we are going to use curl that is easy to use in command line.

The structure of the POST for an annotation item is very simple (API documentation here):

  curl -i -X POST http://myserver.example.com:8090/s/annotation \
       -H "Content-Type: application/json" \
       -d'{"apiKey":"{+SYSTEM_API_KEY}", "outCmd":"frame", "item":{+ANNOTATION}}

Where +SYSTEM_API_KEY is the API key of the previous section and +ANNOTATION is the actual annotation content. Notice also the parameter "outCmd":"frame", this is used to frame the JSON-LD result, which means that the result will always be returned with a precise hierarchical structure so that the clients don't have to deal with the variability of a graph-like representation.

A simple example of Annotation of type Highlight (conformant to the Open Annotation Model) would be:

{
 "@context": "https://raw2.github.com/Annotopia/AtSmartStorage/master/web-app/data/OAContext.json",
 "@id": "urn:temp:7",
 "@type": "oa:Annotation",
 "motivatedBy": "oa:highlighting",
 "annotatedBy": {
  "@id": "http://orcid.org/0000-0002-5156-2703",
  "@type": "foaf:Person",
  "foaf:name": "Paolo Ciccarese"
 },
 "annotatedAt": "2014-02-17T09:46:11EST",
 "serializedBy": "urn:application:utopia",
 "serializedAt": "2014-02-17T09:46:51EST",
 "hasTarget": {
  "@id": "urn:temp:8",
  "@type": "oa:SpecificResource",
  "hasSelector": {
   "@type": "oa:TextQuoteSelector",
   "exact": "senior scientist and software engineer",
   "prefix": "I am a",
   "suffix": ", working in the bio-medical informatics field since the year 2000"
  },
  "hasSource": {
   "@id": "http://paolociccarese.info",
   "@type": "dctypes:Text"
  }
 }
}

Note that:

• the '@context' is necessary for the server to interpret the content
• the '@id' fields contain a temporary value. In fact, when posting an annotation for the first time, the server will mint URIs for Annotation and Target and will return the updated content to the client as a response of the POST
• the 'motivatedBy' property declares that the intent of the annotation is of highlighting.
• the 'hasTarget' uses a quote of the annotated piece of content. 
• the 'hasSource/@id' represents the URI of the annotated resource
• the 'hasSelector' identifies a fragment of that resource.
• the 'serializedBy' declares which system created the artifact. In the above case it is the Utopia for PDF application. Domeo would  be urn:application:domeo**.

** Note that this aspect is not fully implemented yet, therefore only specific systems are recognized by Annotopia and used for filtering. All others are managed but not exploited. In other words, currently only two values are fully manage 'urn:application:domeo' and 'urn:application:utopia'. Alternative values can be used and stored but they will not appear in the facets.  for search.

A simpler example of Annotation of type Comment of an entire resource:

{
    "@context": "https://raw2.github.com/Annotopia/AtSmartStorage/master/web-app/data/OAContext.json",
    "@id": "urn:temp:001",
    "@type": "http://www.w3.org/ns/oa#Annotation",
    "motivatedBy": "oa:commenting",
    "annotatedBy": {
        "@id": "http://orcid.org/0000-0002-5156-2703",
        "@type": "foaf:Person",
        "foaf:name": "Paolo Ciccarese"
    },
    "annotatedAt": "2014-02-17T09:46:11EST",
    "serializedBy": "urn:application:domeo",
    "serializedAt": "2014-02-17T09:46:51EST",
    "hasBody": {
        "@type": [
            "cnt:ContentAsText",
            "dctypes:Text"
        ],
        "cnt:chars": "This is an interesting document",
        "dc:format": "text/plain"
    },
    "hasTarget": "http://paolociccarese.info"
}

Note that:

• the 'hasBody' shows how to encode textual content
• the 'hasTarget' is just a URI**.

** Note that as the target is a URI, anything identifiable can be annotated. In the above case we are annotating a web page, but the URI could be the identifier for a Data point as well.

Once the POST is sent, if everything is correct, the server (if "outCmd":"frame" was specified) will return a result message that has the following structure:

{"status":"saved", "result": {"duration": "1764ms","graphs":"1","item":[{
  "@context" : {
    ...
  },
  "@graph" : [ {
    "@id" : "http://myserver.example.com:8090/s/annotation/597C3DE9-8657-4FA6-ABCA-895A74B448E9",
    "@type" : "oa:Annotation",
    "http://purl.org/pav/previousVersion" : "urn:temp:7",
    "annotatedAt" : "2014-02-17T09:46:11EST",
    "annotatedBy" : {
      "@id" : "http://orcid.org/0000-0002-5156-2703",
      "@type" : "foaf:Person",
      "name" : "Paolo Ciccarese"
    },
    "hasTarget" : {
      "@id" : "http://myserver.example.com:8090/s/resource/ED20AE10-4916-485C-903D-54D6F11DF682",
      "@type" : "oa:SpecificResource",
      "http://purl.org/pav/previousVersion" : "urn:temp:8",
      "hasSelector" : {
        "@id" : "_:b0",
        "@type" : "oa:TextQuoteSelector",
        "exact" : "senior scientist and software engineer",
        "prefix" : "I am a",
        "suffix" : ", working in the bio-medical informatics field since the year 2000"
      },
      "hasSource" : {
        "@id" : "http://paolociccarese.info",
        "@type" : "dctypes:Text"
      }
    },
    "motivatedBy" : "oa:highlighting",
    "serializedAt" : "2014-02-17T09:46:51EST",
    "serializedBy" : "urn:application:utopia"
  } ]
}]}}

Note that:

• the updated message is stored in the "item" section in a '@graph'
• the '@id' have been updated with resolvable URIs
• the property "http://purl.org/pav/previousVersion" returns the original temporary '@id' for matching.

Step 3. How to include bibliographic metadata/identifiers

Annotopia can use identifiers (PubMed IDs, PubMed Central IDs, DOIs and PIIs) to resolve equivalent documents. For example a HTML version of the document vs a PDF version. Or multiple HTML versions of the same document.

To include bibliographic metadata identifiers in the annotation, is sufficient to add the data to the 'hasSource' section as follows:

"hasSource": {
 "@id": "http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3102893/",
 "@type": "dctypes:Text",
 "format": "text/html",
 "http://purl.org/vocab/frbr/core#embodimentOf": {

                "http://purl.org/dc/terms/title":"An open annotation ontology for science on web 3.0",

                "http://prismstandard.org/namespaces/basic/2.0/doi": "10.1186/2041-1480-2-S2-S4",
  "http://purl.org/spar/fabio#hasPII": "2041-1480-2-S2-S4",
  "http://purl.org/spar/fabio#hasPubMedCentralId": "PMC3102893",
  "http://purl.org/spar/fabio#hasPubMedId": "21624159"
 }
}

Step 4. Request for a specific annotation (GET {$id})

For requesting a specific annotation through its URI it is sufficient to execute (see API docs):

    curl -i -X GET +ANNOTATION_URI -H "Content-Type: application/json" \
       -d'{"apiKey":"+SYSTEM_API_KEY","outCmd":"frame"}'

Step 4. Request for annotations for a document (GET)

It is common to request the annotation for a particular document by URI (see API docs):

    curl -i -X GET http://myserver.example.com:8090/s/annotation \
      -H "Content-Type: application/json" \
      -d '{"apiKey":"+SYSTEM_API_KEY","tgtUrl":"http://www.jbiomedsem.com/content/2/S2/S4"}'

Or by bibliographic identifier:

    curl -i -X GET http://myserver.example.com:8090/s/annotation \
      -H "Content-Type: application/json" \
      -d '{"apiKey":"+SYSTEM_API_KEY","tgtIds":"{'pii':'2041-1480-2-S2-S4'}"}'

Adding bibliographic data to Open Annotation

One of the challenges for achieving interoperability between annotation clients that deal with different formats (for example PDF and HTML, see previous post Domeo and Utopia integration through Annotopia) is to be able to identify the annotated content.

For example, let's consider the paper about Annotation Ontology: Ciccarese P, Ocana M, Castro LJG, Das S, Clark, T. An open annotation ontology for science on web 3.0. J Biomed Semantics 2011, 2(Suppl 2):S4 (17 May 2011) [doi:10.1186/2041-1480-2-S2-S4]

Besides this PDF version (there might be others) of the article:
* PDF at Journal of Biomedical Semantics

The manuscript can be found in HTML format at least in these two locations (which exhibits different layouts):
* PubMed Central
* Journal of Biomedical Semantics

We know that the same content can be identified through identifiers:
* DOI (Digital Object Identifier) 10.1186/2041-1480-2-S2-S4
* PMID (PubMed ID) 21624159
* PMCID (PubMed Central ID) PMC3102893
* PII (Publisher Item Identifier) 2041-1480-2-S2-S4

In order to take into account all the available identifiers, it is possible to include in the annotation target the additional information. So if the client is annotating the PubMed Central version of the document (identified by the URL http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3102893/), the source of the target will be identified by:

 ...
    "hasSource": {
        "@id": "http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3102893/",
        "@type": "dctypes:Text",
        "frbr:embodimentOf" : 
        { 
            "prism:doi": "10.1186/2041-1480-2-S2-S4",
            "fabio:hasPII":"2041-1480-2-S2-S4",
            "fabio:hasPubMedCentralId":"PMC3102893",
            "fabio:hasPubMedId":"21624159"
        }
        
    }

Where I made use of the FaBiO (FRBR aligned bibliographic Ontology) ontology which, in turns, reuse term from the FRBR ontology and the PRISM vocabulary. Kudos to Silvio Peroni for pointing out that the relationship between the Manifestation (HTML page) and the Expression should be frbr:embodimentOf and not fabio:manifestationOf. The latter would assume the identifiers are identifying the Work.

Domeo and Utopia integration through Annotopia

Here is a very recent demo of annotation created on a HTML document through Domeo and then seen on the correspondent PDF with the Utopia PDF viewer. All through Open Annotation and Annotopia.

Thanks to Steve Pettifer and Dave Thorne (for the Utopia plugin development); Thomas Wilkins for OAuth implementation in Annotopia. Annotopia is currently architected and developed by me.

Annotopia: Creation/updates with Open Annotation (?)

I am currently developing the Annotopia Open Annotation server [GitHub, Living Slides, Talk 'I Annotate 2014'] and there are a few topics related to the application of the Open Annotation Model that might need further discussion within the community. I will start with one

:: Date/agent of annotation creation and update ::

Even if we don't have the need to support versioning (this will be subject of a future post) and in the unlikely event that the annotation cannot be edited we often need to be able to keep track of who/when the annotation has been created and, eventually, updated. 

Open Annotation Provenance Model

The Open Annotation Model now supports the following provenance relationships/properties:

Vocabulary Item	Type	Description
oa:annotatedBy	Relationship	[subProperty of prov:wasAttributedTo] The object of the relationship is a resource that identifies the agent responsible for creating the Annotation. This may be either a human or software agent. There SHOULD be exactly 1 oa:annotatedBy relationship per Annotation, but MAY be 0 or more than 1, as the Annotation may be anonymous, or multiple agents may have worked together on it.
oa:annotatedAt	Property	The time at which the Annotation was created. There SHOULD be exactly 1 oa:annotatedAt property per Annotation, and MUST NOT be more than 1. The datetime MUST be expressed in the xsd:dateTime format, and SHOULD have a timezone specified.
oa:serializedBy	Relationship	[subProperty of prov:wasAttributedTo] The object of the relationship is the agent, likely software, responsible for generating the Annotation's serialization. There MAY be 0 or more oa:serializedBy relationships per Annotation.
oa:serializedAt	Property	The time at which the agent referenced by oa:serializedBy generated the first serialization of the Annotation, and any subsequent substantially different one. The annotation graph MUST have changed for this property to be updated, and as such represents the last modified datestamp for the Annotation. This might be used to determine if it should be re-imported into a triplestore when discovered. There MAY be exactly 1 oa:serializedAt property per Annotation, and MUST NOT be more than 1. The datetime MUST be expressed in the xsd:dateTime format, and SHOULD have a timezone specified.

So we can encode when the annotation has been created and usually that coincides with the time when the user created the annotation on the user interface of the annotation client.

Then the annotation is sent to the server to be persisted.

Do nothing approach

One possible approach, that I would rather not advocate for, is to forget about the concepts of creation and update: 'every time a change is performed on an annotation, the old instance is swapped with the new one. The new one replaces entirely the previous annotation and shares the same URI.'. In this case, 'annotatedAt' is always referring to the latest annotation event (no matter if it was the original creation or following updates). 

Use a richer provenance model

To be a little more exhaustive, in Annotopia, as I was doing in Domeo and Annotation Ontology, I could use a series of properties of PAV (Provenance, Authoring and Versioning) ontology [paper]: pav:createdOn (when it has been created), pav:createdBy (who created it), pav:lastUpdateOn (when it has been last updated), pav:lastUpdateBy (who last updated the annotation).

So I could say:

Option A: Add lastUpdateOn

In this scenario we use annotatedAt/annotatedBy for the annotation creation and lastUpdateOn/lastUpdateBy for the last update.

{
    "@id" : "http://host/s/annotation/830ED7EE-BF7B-4A18-8AE1-A9AF96AC135B",
    "@type" : "oa:Annotation",
    "annotatedAt" : "2014-02-17T09:46:11EST",
    "annotatedBy" : {
      "@id" : "http://orcid.org/0000-0002-5156-2703",
      "@type" : "foaf:Person",
      "name" : "Paolo Ciccarese"
    },
    "pav:lastUpdateOn" : "2014-03-11T11:46:11EST",
    "pav:lastUpdateBy" : {
      "@id" : "http://example.org/johndoe",
      "@type" : "foaf:Person",
      "name" : "John Doe"
    }
...
}

In this case, both events would refer to when the act has been performed on the user interface (?).

Option B: Add createdOn and lastUpdateOn

Here we make use of annotatedAt/annotatedBy, createdOn/createdBy and  lastUpdateOn/lastUpdateBy

{
    "@id" : "http://host/s/annotation/830ED7EE-BF7B-4A18-8AE1-A9AF96AC135B",
    "@type" : "oa:Annotation",
    "pav:previousVersion" : "urn:temp:001",
    "annotatedAt" : "2014-02-17T09:46:11EST",
    "annotatedBy" : {
      "@id" : "http://orcid.org/0000-0002-5156-2703",
      "@type" : "foaf:Person",
      "name" : "Paolo Ciccarese"
    },
    "pav:createdOn" : "2014-02-17T09:48:11EST",
    "pav:createdBy" : {
      "@id" : "http://orcid.org/0000-0002-5156-2703",
      "@type" : "foaf:Person",
      "name" : "Paolo Ciccarese"
    },
    "pav:lastUpdateOn" : "2014-03-11T11:46:11EST",
    "pav:lastUpdateBy" : {
      "@id" : "http://example.org/johndoe",
      "@type" : "foaf:Person",
      "name" : "John Doe"
    }
...
}

In this case it is necessary to agree on the semantics of all those properties. I could use:
(i) 'createdOn/createdBy' for the original creation on the (Annotopia) server
(ii) 'lastUpdateOn/lastUpdateBy' for the last update on the (Annotopia)  server
(iii) and what is  'annotatedAt' going to indicate? The original creation or the latest update? And how do I keep track of the agents involved?