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
5. Editing an annotation body
6. Managing permission lists of users
   1. Adding and deleting users in permission lists
   2. Adding a user with a certain permission
   3. Removing a reader or a writer
7. Managing annotations
   1. Deleting an entire annotation (if <uid> is an owner)
8. Notebooks
   1. Retrieve notebooks Info
   2. Retrieve notebook info
   3. Retrieving the list of annotations in a notebook if <uid> has a read access to this notebook
   4. Adding an annotation to a notebook

---

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 GET api/annotations/<aid>
• Client: get the unresolved source GET api/sources/<sid>
• Client: get the version list of the unresolved source GET api/versions/<vid>
• Client: get cached representations for the considered version GET api/sources/<sid>/cached/<cid>/metadata

See:

• example unresolvable target sources step 1,
• example unresolvable target sources step 2,
• example unresolvable target sources step 3
• 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 Example: body of the POST submitting a new annotation.

See also UGOT example.

• Service: responds with the envelope: {<annot'>, <Actions>*}. <annot'> is a newly-created in the DB annotation obtained from the POSTed new <annot> 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 Response (an envelope) on creating a new annotation.

• Client: sends cached representation POST/api/cources/<sid>/cached
• Service: store representation

Editing an annotation body

PUT api/annotations/<aid>

Request body: XML new body <annot>, see Updated annotation body.

Response: the envelope, see Response on updating annotation body .

Managing permission lists of users

Give the list of the users for a given annotation/notebook

GET api/annotations/<aid>/permissions

Response: see 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 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/<aid>/permissions

Request body contains the list of permissions, see Update permission list?

Response is the envelope.

Adding a user with a certain permission

PUT api/annotations/<aid>/permissions/<uid>

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/<aid>/permissions/<uid>

No enveloped response, just an http status code

Managing annotations

Deleting an entire annotation (if <uid> is an owner)

DELETE api/annotations/<aid>

No enveloped response, just an http status code

Notebooks

Retrieve notebooks Info

GET api/notebooks

Response: the list of notebooks.

Retrieve notebook info

GET api/notebooks/<nid>

Response: Notebook Info

Retrieving the list of annotations in a notebook if <uid> has a read access to this notebook

GET api/notebooks/<nid>/annotations/

Response: the list of annotation Info.

Adding an annotation to a notebook

PUT api/notebooks/<nid>/<aid>

Response: only a http status code.