Version 21 (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, so the UID gets known by the server. See SpecificationDocument#Userrealm and XSD and XML#RespondingGETapiuseruid
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?source="http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read
- Service: returns list of annotation id-s with the corresponding headlines, notebooks, owners, and target source ID's;
See XSD and XML#RespondingGETapiannotationssourcehttp:en.wikipedia.orgwikiSagrada_FamC3ADliaaccessread
- Client: Resolving fragments (mapping) happens after the response. There are two internal lists for the client: the resolvable and unresolvable target.
Viewing an individual annotation
Resolvable target
- User: selects an annotation with "at least one resolvable" (debatable) target for reading.
- Client: retrieves the annotation
GET api/annotations/<aid>
- Service: returns the annotation
See XSD and XML#RespondingGETapiannotationsAID02exampleusageforresolvabletargetsources.
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 XSD and XML#RespondingGETapiannotationsAID01exampleusageforunresolvabletargetsources, XSD and XML#RespondingGETapiannotationsAID01sourcesexampleusageforunresolvabletargetsources, XSD and XML#RespondingGETapisourcesSID05cachedCID005Ametadataexampleusageforunresolvabletargetsources.
Annotation creation
- User: creates a text note on a selected text.
- Client: sends the annotation to the server
POST api/annotation
- Example:
<?xml version="1.0"?> <annotation xmlns="http://dasish.eu/ns/addit" xmlns:xhtml="http://www.w3.org/1999/xhtml" URI="tempAIDgfgf" timeStamp="2013-04-26T11:23:26.000Z"> <owner ref="http://dasish.eu/users/user123"/> <headline>Douglas Adams - Wikipedia, the free encyclopedia</headline> <body type="Note"> <xhtml:span style="background-color:rgb(253,49,31);color:rgb(0,0,0);">Adams was born 1952-03-11</xhtml:span> </body> <targetSources> <action>CREATE_CACHED_REPRESENTATION</action> <link>http://en.wikipedia.org/wiki/Douglas_adams#xpointer(start-point(string-range(//div[@id="mw-content-text"]/table[1]/tbody[1]/tr[3]/td[1]/text()[1],'',12))/range-to(string-range(//div[@id="mw-content-text"]/table[1]/tbody[1]/tr[3]/td[1]/text()[1],'',25)))</link> <version>2013-04-26T11:23:26.000Z</version> </targetSources> </annotation>
See XSD and XML#RequestbodyforPOSTapiannotations, two versions, with and without action "CREATE_CACHED_REPRESENTATION".
- 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
TODO
Managing readers and writers
Adding readers and writers
TODO
Removing readers and writers
TODO
Managing annotations
Deleting an entire annotation
TODO
Notebooks
Retrieving list of annotations in a notebook
TODO
Adding an annotation to a notebook
TODO