Web-annotator/API interaction scenarios

Contents

1. Authentication
2. Visiting an annotated web page
3. Viewing an individual annotation
   1. Resolvable target
   2. Unresolvable target
4. Annotation creation
   1. Olha's question
5. Editing an annotation body
6. Managing readers and writers
   1. Adding readers and writers
   2. Removing readers and writers
7. Managing annotations
   1. Deleting an entire annotation
8. Notebooks
   1. Retrieving list of annotations in a notebook
   2. Adding an annotation to a notebook

---

ToDo: (general): add example XML serializations of requests/responses to serve as basis for (modifications of) the schemata.

Status. Partially done.

Authentication

• User logs-in to annotation service, "uid" gets known by the server. See DASISH specification: user realm and 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 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/<aid>
• Service: returns the annotation

See Example: obtaining an annotation with resolvable target sources.

Unresolvable target

• User: select an annotation with unresolvable targets for reading.
• Client: get annotation and its target sources
• GET api/annotations/<aid>
• GET api/annotations/<aid>/sources
• Client: get cached representations for target sources
• GET api/sources/<sid>/cached/<cid>/metadata

See Example: getting an annotation with an unresolvable target source, Example: getting target sources for the annotation, Example: getting a cached representation for the unresolvable target source.

Annotation creation

• User: creates a text note on a selected text.
• Client: sends the annotation to the server
• POST api/annotation

See Example: body of the POST submitting a new annotation.

See also | UGOT example.

• Service: responds with the annotation <aid>, 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/<sid>/cached

Olha's question

The serialisation is an instance of the same element as the serialization of the respond on GET api/sources/<sid>/cached/<cid>. Agree?

• Service: store representation

Editing an annotation body

TODO

Managing readers and writers

Adding readers and writers

TODO

Removing readers and writers

TODO

Managing annotations

Deleting an entire annotation

TODO

Notebooks

Retrieving list of annotations in a notebook

TODO

Adding an annotation to a notebook

TODO