}}}
[[PageOutline(1-3, , inline)]]
----
'''ToDo:''' (general): add example XML serializations of requests/responses to serve as basis for (modifications of) the schemata.
'''Status'''. Partially done.
= Authentication =
* User logs-in to annotation service, "uid" gets known by the server. See [[SpecificationDocument#Userrealm | DASISH specification: user realm]] and [[XSD and XML#RespondingGETapiuseruid | Example: getting user information, incl. current-user flag]]
= Visiting an annotated web page =
* User: visits the page {{{http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia}}} (for example).
* Client: requests the lists of annotations to which the user has "read" access.
* {{{GET api/annotations?link="http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read}}}
* Service: returns list of annotation URI-s with the corresponding headlines, owners, and target source refs (URI-s);
See [[XSD and XML#RespondingGETapiannotationslinkhttp:en.wikipedia.orgwikiSagrada_FamC3ADliaaccessread | Example: getting annotations for Sagrada Famiglia wiki-page]]
* Client: Resolving fragments (mapping) happens after the response. There are two internal lists for the client: the resolvable and unresolvable targets.
= Viewing an individual annotation =
== Resolvable target ==
* User: selects an annotation with "at least one resolvable" ('''TODO''': at least one? discuss) target for reading.
* Client: retrieves the annotation
* {{{GET api/annotations/}}}
* Service: returns the annotation
See [[XSD and XML#RespondingGETapiannotationsAIDzzzexampleofresolvabletargetsources | Example: obtaining an annotation with resolvable target sources].
== Unresolvable target ==
* User: select an annotation with unresolvable targets for reading.
* Client: get annotation and its target sources
* {{{GET api/annotations/}}}
* {{{GET api/annotations//sources}}}
* Client: get cached representations for target sources
* {{{GET api/sources//cached//metadata}}}
See [[XSD and XML#RespondingGETapiannotationsAIDzyyexampleusageforunresolvabletargetsources | Example: getting an annotation with an unresolvable target source]], [[XSD and XML#RespondingGETapiannotationsAIDzyysourcesexampleusageforunresolvabletargetsources | Example: getting target sources for the annotation]], [[XSD and XML#RespondingGETapisourcesSIDbbbcachedCIDttttmetadataexampleusageforunresolvabletargetsources | Example: getting a cached representation for the unresolvable target source]].
= Annotation creation =
* User: creates a text note on a selected text.
* Client: sends the annotation to the server
* {{{POST api/annotation}}}
See [[XSD and XML#RequestbodyforPOSTapiannotations | Example: body of the POST submitting a new annotation]]
* Example UGOT:
{{{
Douglas Adams - Wikipedia, the free encyclopediaAdams was born 1952-03-11CREATE_CACHED_REPRESENTATION
http://en.wikipedia.org/wiki/Douglas_adams#xpointer(start-point(string-range(//div[@id="mw-content-text"]/table[1]/tbody[1]/tr[3]/td[1]/text()[1],'',12))/range-to(string-range(//div[@id="mw-content-text"]/table[1]/tbody[1]/tr[3]/td[1]/text()[1],'',25)))
2013-04-26T11:23:26.000Z
}}}
* Service: responds with the annotation , with temp id-s replaced by the permanent ones, the full URI for the target sources, action:create cached representation.
* Client: sends cached representation
* {{{POST/api/cources//cached}}}
== Olha's question ==
The serialisation is an instance of the same element as the serialization of the respond on {{{GET api/sources//cached/}}}. Agree?
* Service: store representation
= Editing an annotation body =
'''TODO'''
= Managing readers and writers =
== Adding readers and writers ==
'''TODO'''
== Removing readers and writers ==
TODO
= Managing annotations =
== Deleting an entire annotation ==
'''TODO'''
= Notebooks =
== Retrieving list of annotations in a notebook ==
'''TODO'''
== Adding an annotation to a notebook ==
'''TODO'''