'''Web-annotator/API interaction scenarios''' {{{ #!html

Contents

}}} [[PageOutline(1-3, , inline)]] ---- = Authentication api/authentication/login = * If a principal logs-in to annotation service, "prid" gets known by the server. The principal's information can be seen at e.g. [[XSD and XML#GETapiprincipals00000000-0000-0000-0000-000000000112 | GET api/principals/00000000-0000-0000-0000-000000000112]] = Visiting an annotated web page = * Principal: visits the page {{{http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia}}} (for example). * Client: requests the lists of annotations to which the principal has "read" access. {{{GET api/annotations?link="http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read}}} * Service: returns list of annotation info: URI-s with the corresponding headlines, owners, and target source refs (URI-s); See [[XSD and XML#RespondingGETapiannotationslinkSagrada | Example: getting annotations for Sagrada Famiglia wiki-page]] If the client cannot fit annotated fragments into the current version of the document, the corresponding target source is called unresolved. Unresolvability of a target source triggers the client-side workflow of getting a cached representation of the concerning version of the source. = Viewing an individual annotation = == Resolvable target == * Principal: selects an annotation (with resolvable targets) for reading. * Client: retrieves the annotation * {{{GET api/annotations/}}} * Service: returns the annotation See [[XSD and XML#RespondingGETapiannotations00000000-0000-0000-0000-000000000021 | Example: getting an annotation]]. == Unresolvable target == * Principal: select an annotation with unresolvable targets for reading. * Client: get annotation {{{GET api/annotations/}}} * Client: get the unresolved target {{{GET api/targets/}}} * Client: get the version list of the unresolved source {{{GET api/targets//versions}}} and the principal (??) selects one of them. * Client: gets the selected version of the target {{{GET api/targets/}}} * Client: get cached representations for the considered version {{{GET api/cached//stream}}} and {{{GET api/cached//metadata}}} See: * [[XSD and XML#RespondingGETapiannotations00000000-0000-0000-0000-00000000002cexampleusageforunresolvabletargetsstep1 | example unresolvable target step 1]], * [[XSD and XML#RespondingGETapitargets00000000-0000-0000-0000-00000000003cunresolvabletargetsourcesstep2thesameasforresolvablejustthelinkisbrokenorobsolete | example unresolvable target step 2]], * [[XSD and XML#RespondingGETapitargets00000000-0000-0000-0000-00000000003cversionsunresolvabletargetsourcesstep3 | example unresolvable target step 3]], * [[XSD and XML#RespondingGETapicached00000000-0000-0000-0000-000000000052metadataunresolvabletargetsourcesstep5 | example unresolvable target sources step 5]]. = Annotation creation = * Principal: 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 a new annotation]]. * Service: responds with the envelope: {, *}. is the serialisation of the newly-created in the DB annotation obtained from the POSTed new by replacing all its temporary target- 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/targets//fragmet/[fragmentdescriptor]/cached}}} * Service: store representation = Editing an annotation body = {{{PUT api/annotations//body}}} Request body: XML new body , see [[XSD and XML#PUTapiannotations1d02f393-da25-4246-934c-876222a2d7fbbody | Updated annotation body]]. Response is given beneath the body example. = Managing permission lists of permissions = A permission is a pair (principal reference, access), where access is "read" or "write". Give the list of the permissions for a given annotation/notebook {{{GET api/annotations//permissions}}} Response: see [[XSD and XML#GETapiannotations00000000-0000-0000-0000-000000000021permissions | List of permissions for a given annotation ]]. == Adding and deleting principals in permission lists == {{{GET api/principals/info?email=<...>}}} Response: Principal (her/his uri, display name, e-mail), see [[XSD and XML#GETapiprincipalsinfoemailtwagoompi.nl | Getting principal via his/her e-mail ]] If a principal with the given e-mail does not exist, status 404 is returned. {{{PUT api/annotations//permissions}}} Request body contains the list of permissions, see [[XSD and XML#PUTapiannotations1d02f393-da25-4246-934c-876222a2d7fbpermissions| Update permission list]]. Response is the envelope. == Adding a principal with a certain access == {{{PUT api/annotations//permissions/}}} Request body contains the access level of this user to this annotation, see [[XSD and XML#PUTapiannotations1d02f393-da25-4246-934c-876222a2d7fbpermissions00000000-0000-0000-0000-000000000114 | Adding/updating a principal 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 logged-in is the owner) == {{{DELETE api/annotations/}}} No enveloped response, just an http status code. = Notebooks (obsolete subpage) = == 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.