| Version 31 (modified by , 11 years ago) (diff) |
|---|
Web-annotator/API interaction scenarios
Contents
- Authentication
- Visiting an annotated web page
- Viewing an individual annotation
- Annotation creation
- Editing an annotation body
- Managing readers and writers
- Managing annotations
- Notebooks
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
PUT
Response: the envelope {A', R*}, make a schema for it!!
The same for posting
Managing readers and writers
ReMOVE readers and writers from the annotations:
Make list of the users with attribute permissions (add to schema!!)
Give the list of the users for a given annotation/notebook
GET api/annotations/<aid>/permissions
Adding/Deleting? readers and writers
GET api/users/info?email=<...>
Response: UID and the display name
PUT api/annotations/<aid>/permissions
body is the list
Response in the envelope
Adding a reader/writer
PUT api/annotations/<aid>/permissions/<uid>
Body contains the access level of this user to this annotation
No body in in response (no envelope), just an http status code
Removing a reader or a writer
DELETE api/annotations/<aid>/permissions/<uid>
No body in the response (no envelope), just an http status code
Managing annotations
Deleting an entire annotation (if <uid> is an owner)
DELETE api/annotations/<aid>
No body in the response (no envelope), just an http status code
Notebooks
Retrieve notebooks Info
GET api/notebooks
Retrieving the list of annotations in a notebook if <uid> has a read access to this notebook
GET api/notebooks/<nid>/annotations/
Response: XML list of annotation Info.
Adding an annotation to a notebook
PUT api/notebooks/<nid>/<aid>
Response: status code
