'''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#RespondingGETapisourcesSIDbbbunresolvabletargetsources2 | example unresolvable target sources step 2]],
* [[XSD and XML#RespondingGETapiversionsVIDaaccunresolvabletargetsources3 | example unresolvable target sources step 3]]
* [[XSD and XML#RespondingGETapisourcesSIDbbbcachedCIDttttmetadataunresolvabletargetsources4 | 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 envelope: {, *}. is a newly-created in the DB annotation obtained from the POSTed new by replacing all its temporary target-source id-s with the corresponding actual references, which are URI's in the DB. The list of actions may be empty or contain "CREATE_CACHED_REPRESENTATION";
See [[XSD and XML#ResponsebodyenvelopeforPOSTapiannotations | Response (an envelope) on creating a new annotation]].
* Client: sends cached representation {{{POST/api/cources//cached}}}
* Service: store representation
= Editing an annotation body =
PUT api/annotations/
Request body: XML new body , see [[XSD and XML#Request:anupdatedbody | Updated annotation body]].
Response: the envelope, see [[XSD and XML#Envelopedrespond:newupdatedannotationandalistofactions | Response on updating annotation body]] .
= Managing permission lists of users =
Give the list of the users for a given annotation/notebook
GET api/annotations//permissions
Response: see [[XSD and XML#GETapiannotationsAIDzyypermissions | List of permissions for a given annotation ]].
== Adding and deleting users in permission lists ==
GET api/users/info?email=<...>
Response: UID and the display name, see
[[XSD and XML#GETapiusersinfoemailalecormpi.nl | Getting user info via his/her e-mail ]]
QUESTION: what to do if no user with this e-mail is found, an http status "page not found" is returned? Or an envelope with the action PROVIDE_USER_INFO?
PUT api/annotations//permissions
Request body contains the list of permissions, see [[XSD and XML#PUTapiannotationsAIDzyypermissions | Update permission list]].
Response is the envelope.
== Adding a user with a certain permission ==
PUT api/annotations//permissions/
Request body contains the access level of this user to this annotation.
No enveloped response, just an http status code.
== Removing a reader or a writer ==
DELETE api/annotations//permissions/
No enveloped response, just an http status code
= Managing annotations =
== Deleting an entire annotation (if is an owner) ==
DELETE api/annotations/
No enveloped response, just an http status code.
= Notebooks =
== Retrieve notebooks Info ==
GET api/notebooks
Response: the list of notebook infos, see [[XSD and XML#GETapinotebooks | Retrieving notebook info list]].
== Retrieve notebook info
GET api/notebooks/
Response: Notebook Info, see [[XSD and XML#GETapinotebooksNIDxyxy | Retrieving notebook info]].
== Retrieving the list of annotations in a notebook if has a read access to this notebook ==
GET api/notebooks//annotations/
Response: the list of annotation Info, see [[XSD and XML#GETapinotebooksNIDxyxyannotations | Retrieving the list of annotations for a notebook]].
== Adding an annotation to a notebook ==
PUT api/notebooks//
Request body: empty.
Response: only a http status code.