Version 51 (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 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
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.