}}}
[[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, so the UID gets known by the server. See [[SpecificationDocument#Userrealm]] and [[XSD and XML#RespondingGETapiuseruid]]
= 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?source="http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read}}}
* Service: returns list of annotation id-s with the corresponding headlines, notebooks, owners, and target source ID's;
See [[XSD and XML#RespondingGETapiannotationssourcehttp:en.wikipedia.orgwikiSagrada_FamC3ADliaaccessread]]
* Client: Resolving fragments (mapping) happens after the response. There are two internal lists for the client: the resolvable and unresolvable target.
= Viewing an individual annotation =
== Resolvable target ==
* User: selects an annotation with "at least one resolvable" (debatable) target for reading.
* Client: retrieves the annotation
* {{{GET api/annotations/}}}
* Service: returns the annotation
See [[XSD and XML#RespondingGETapiannotationsAID02exampleusageforresolvabletargetsources]].
== 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#RespondingGETapiannotationsAID01exampleusageforunresolvabletargetsources]], [[XSD and XML#RespondingGETapiannotationsAID01sourcesexampleusageforunresolvabletargetsources]], [[XSD and XML#RespondingGETapisourcesSID05cachedCID005Ametadataexampleusageforunresolvabletargetsources]].
= Annotation creation =
* User: creates a text note on a selected text.
* Client: sends the annotation to the server
* {{{POST api/annotation}}}
* Example:
{{{
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
}}}
See [[XSD and XML#RequestbodyforPOSTapiannotations]], two versions, with and without action "CREATE_CACHED_REPRESENTATION".
* 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'''