| Version 36 (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
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: a newly-created annotation (with temp id-s replaced by the permanent ones and the full URI for the target sources) + list of actions;
the list of actions may be empty or contain "CREATE_CACHED_REPRESENTATION";
- 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>
Response: the envelope {<annot'>, <Actions>*}.
Managing readers and writers
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
Response: XML list
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: XML list of annotation Info.
Adding an annotation to a notebook
PUT api/notebooks/<nid>/<aid>
Response: status code
