'''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.