Contents

1. Web-annotator/API interaction scenarios
   1. Authentication
   2. Visiting an annotated web page
   3. Viewing an individual annotation
   4. Annotation creation
   5. Editing an annotation body
   6. Managing readers and writers
   7. Managing annotations
   8. Notebooks

---

Web-annotator/API interaction scenarios

TODO add example XML serializations of requests/responses to serve as basis for (modifications of) the schemata

Authentication

• User logs-in to annotation service, so the UID gets known by the server.

TODO: Add to API the "who-am-I" service that allows the user to obtain his/her UID and list of notebooks(read and write), incl. their id's and rendering names.

Visiting an annotated web page

• User: visits the page <...>.
• The client: requests the lists of annotations to which the user has "read" access.
• GET api/annotations?source=<...>&access=read
• The call returns list of annotation id-s with the corresponding headlines, notebooks, owners, and target sources URI's (TODO Olha: example XML +schema of the respond).
• Resolving fragments (mapping) happens after the response. There are two internal lists for the client: the resolvable and unresolvable target.

Viewing an individual annotation

Resolvable target

• User: selects an annotation with "at least one resolvable" (debatable) target for reading.
• The client GET api/annotations/<aid> (Olha, to do: XML of the respond)

Unresolvable target

• User: select an annotation with unresolvable targets for reading.
• The client: GET api/annotations/<aid> (Olha, to do: example XML+schema of the respond, for all 4 calls),
• GET api/annotations/<aid>/sources
• GET api/sources/<sid>/cached
• GET api/sources/<sid>/cached/<cid>

Annotation creation

• User: creates a text note on a selected text.
• The client: POST api/annotation (Olha, to do: input example XML+schema of the body, like in the example)
• Response: the annotation <aid>, with temp id-s replaced by the permanent ones, the full URI for the target sources,
• action:create cached representation.
• Followed by POST/api/cources/<sid>/cached

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