APIs for Annotations
Below some of the API documentation for annotations I’ve found from existing projects.
Diigo
Diigo’s API documentation is quite straightforward. Here’s a POST request:
POST https://secure.diigo.com/api/v2/bookmarks ¬
?key=your_api_key ¬
&url=http%3A%2F%2Fwww.diigo.com ¬
&title=Diigo+-+Web+Highlighter+and+Sticky+Notes ¬
&tags=diigo,bookmark,highlight ¬
&shared=yes
And here’s a typical HTTP GET request:
https://secure.diigo.com/api/v2/bookmarks?key=your_api_key&user=joel&count=10
And here a typical result in JSON:
[
{
"title":"Diigo API Help",
"url":"http://www.diigo.com/help/api.html",
"user":"foo",
"desc":"",
"tags":"test,diigo,help",
"shared":"yes",
"created_at":"2008/04/30 06:28:54 +0800",
"updated_at":"2008/04/30 06:28:54 +0800",
"comments":[],
"annotations":[]
},
{
"title":"Google Search",
"url":"http://www.google.com",
"user":"bar",
"desc":"",
"tags":"test,search",
"shared":"yes",
"created_at":"2008/04/30 06:28:54 +0800",
"updated_at":"2008/04/30 06:28:54 +0800",
"comments":[],
"annotations":[]
}
]
AnnotateIt
AnnotateIt seems to be one of the few remaining actively developed Services. It come with quite some nice documentation for setting up the annotation server. Here is the Annotator API to the local couchDB:
http://localhost:5000/search?uri=myuri&user=myuser
And here a supposed example of storing an annotation (not tested yet):
POST http://localhost:5000/annotations ¬
-H "Content-Type: application/json" ¬
-d '{ ... "text": "abc", "id": MY-ID ... }'
Annotea
The now defunct Annotea had a quite nice protocol which used (verbose) RDF as container. Here’s an example:
POST /Annotation HTTP/1.1
Host: annotea.example.org
Content-Type: application/xml
Content-Length: 1254
<?xml version="1.0" ?>
<r:RDF xmlns:r="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:a="http://www.w3.org/2000/10/annotation-ns#"
xmlns:d="http://purl.org/dc/elements/1.1/"
xmlns:tr="http://www.w3.org/2001/03/thread#"
xmlns:h="http://www.w3.org/1999/xx/http#"
xmlns:rt:"http://www.w3.org/2001/12/replyType">
<r:Description>
<r:type r:resource="http://www.w3.org/2001/03/thread#Reply"/>
<r:type r:resource="http://www.w3.org/2001/12/replyType#Agree"/>
<tr:root r:resource="http://annotea.example.org/Annotation/3ACF6D754"/>
<tr:inReplyTo r:resource="http://annotea.example.org/Annotation/3ACF6D754"/>
<d:title>Annotation of Sample Page</d:title>
<d:creator>Marja</d:creator>
<a:created>1999-10-14T12:10Z</a:created>
<d:date>1999-10-14T12:10Z</d:date>
<a:body>
<r:Description>
<h:ContentType>text/html</h:ContentType>
<h:ContentLength>221</h:ContentLength>
<h:Body r:parseType="Literal">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Marja's Reply</title>
</head>
<body>
<p>I agree with Ralph. What would be the next step?</a>.</p>
</body>
</html>
</h:Body>
</r:Description>
</a:body>
</r:Description>
</r:RDF>
</code>
Interestingly, the ‘pay load’ (r:Description/a:body) can be a URL, simple text, or HTML (or MathML, SVG, for that matter).
A typical request for an annotation to a certain resource was supposed to look like this:
GET /Annotation?w3c_annotates=http://serv1.example.com/some/page.html HTTP/1.1
Host: annotea.example.org
Accept: application/xml
And here a request for replies to an annotation:
GET /Annotation
?w3c_reply_tree=http://annotea.example.org/Annotation/3ACF6D754/2DCC6DF41 HTTP/1.1
Host: annotea.example.org
Accept: application/xml