'''Web-annotator/API interaction scenarios'''
{{{
#!html
Contents
}}}
[[PageOutline(1-3, , inline)]]
----
= 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 {{{GET api/annotations/}}}
* Client: get the unresolved source {{{GET api/sources/}}}
* Client: get the version list of the unresolved source {{{GET api/versions/}}}
* Client: get cached representations for the considered version {{{GET api/sources//cached//metadata}}}
See:
* [[XSD and XML#RespondingGETapiannotationsAIDzyyexampleusageforunresolvabletargetsources1 | example unresolvable target sources step 1]],
* [[XSD and XML#RespondingGETapisourcesSIDbbbexampleusageforunresolvabletargetsources2 | example unresolvable target sources step 2]],
* [[XSD and XML#RespondingGETapisourcesSIDbbbexampleusageforunresolvabletargetsources3 | example unresolvable target sources step 3]]
* [[XSD and XML#RespondingGETapisourcesSIDbbbcachedCIDttttmetadataexampleusageforunresolvabletargetsources4 | example unresolvable target sources step 4]].
= 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]].
See also [[XSD and XML#RequestbodyforPOSTapiannotations:anotherexample | UGOT example]].
* 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}}}
* Service: store representation
= Editing an annotation body =
PUT api/annotations/
Request: XML new body A
Response: the envelope {A', R*}, make a schema for it!!
= Managing readers and writers =
ReMOVE readers and writers from the annotations:
Make list of the users with attribute permissions (add to schema!!)
Give the list of the users for a given annotation/notebook
GET api/annotations//permissions
== Adding/Deleting readers and writers ==
GET api/users/info?email=<...>
Response: UID and the display name
PUT api/annotations//permissions
body is the list
Response in the envelope
== Adding a reader/writer ==
PUT api/annotations//permissions/
Body contains the access level of this user to this annotation
No body in in response (no envelope), just an http status code
== Removing a reader or a writer ==
DELETE api/annotations//permissions/
No body in the response (no envelope), just an http status code
= Managing annotations =
== Deleting an entire annotation (if is an owner) ==
DELETE api/annotations/
No body in the response (no envelope), just an http status code
= Notebooks =
== Retrieve notebooks Info ==
GET api/notebooks
Response: XML list
== Retrieve notebook info
GET api/notebooks/
Response Notebook Info
== Retrieving the list of annotations in a notebook if has a read access to this notebook ==
GET api/notebooks//annotations/
Response: XML list of annotation Info.
== Adding an annotation to a notebook ==
PUT api/notebooks//
Response: status code