'''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. QUESTION 1: How to signalise a client that certain sources are not resolved? To send the list of not-resolved targets in the respond? To make an envelope for GET as well? = 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}}} The whole workflow is as follows. 1) At a start an annotation is GET and an unresolved target is detected. An "unresolved target" means that e.g. the corresponding page has been updated and the target fragment cannot be placed within it any more. Therefore, the client needs to get a corresponding cached representation instead of the actual page. 2) For this the clients GETs the source info. It contains: a) the version string, b) the list of the reference ID's all "siblings"-versions of the source for which there are cached representations in the DB. 3) GET the version list. It gives the list of references to the version's cached representations for any version string. Therefore, having the version string, he client can choose a cached representation ID (CID). 4) GET a cached representation by the appropriate CID. See: * [[XSD and XML#RespondingGETapiannotationsAIDzyyexampleusageforunresolvabletargetsources1 | example unresolvable target sources step 1]], * [[XSD and XML#RespondingGETapisourcesSIDbbbunresolvabletargetsources2 | example unresolvable target sources step 2]], * [[XSD and XML#RespondingGETapisourcesSIDbbbversionsunresolvabletargetsources3 | 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 2: 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, see [[XSD and XML#PUTapiannotationsAIDzyypermissionsUIDagc | Adding a user with a specific permission]]. 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.