Version 53 (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 permission lists of users
- 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.
QUESTION 1: How to signalise a client that certain sources are not resolved? To send the list of not-resolved targets in the respond? To make an envelope for GET as well?
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
The whole workflow is as as follows.
1) At a start an annotation is GET and an unresolved target is detected. An "unresolved target" means that e.g. the corresponding page has been updated and the target fragment cannot be placed within it any more. Therefore, the client needs to get a corresponding cached representation instead of the actual page.
2) For this the clients GETs the source info. The source contains: a) the version string, b) the list of the reference ID's all "siblings"-versions of the source for which there are cached representations in the DB. Now the client finds the version ID by the version string.
3) GET the version info. It gives the list of references to the version's cached representations.
4) GET a cached representation.
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 2: 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, see Adding a user with a specific permission.
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 notebook infos, see Retrieving notebook info list.
Retrieve notebook info
GET api/notebooks/<nid>
Response: Notebook Info, see Retrieving 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, see Retrieving the list of annotations for a notebook.
Adding an annotation to a notebook
PUT api/notebooks/<nid>/<aid>
Request body: empty.
Response: only a http status code.