Log in

Community Page

This is a Connotea Community Page. The Community Pages are a wiki, which means that any user can freely create new pages and edit existing ones.

You don't need any special technical knowledge to edit these pages.

Navigate

Help

? means that the link is for a Community Page that hasn't been created yet.

Some text highlighted in red means that there's an error in the wiki page code near that text. Feel free to correct it!

To create a new page, click on an existing link, or use the form below.

Be sure to link to your new page from another page, so readers can find it!

Edit This Page

Connotea Web API Version 0.1

The Connotea Web API is currently still in an experimental phase.

It works well, and you can definitely build services on top of it. If you do, your feedback will help in refining the API further. However, you should be aware that some of the details given below may change before we reach version 1.0.

Currently Supported Operations

Version 0.1 of the Connotea Web API supports the following operations:

Retrieving a list of bookmarks
Retrieving a list of posts
Retrieving a list of tags
Creating a new post
Editing an existing post
Removing an existing post

A Note on Names

What is a bookmark? What is a post? What is the difference?

A bookmark, in Connotea terminology, consists of a basic URL along with a few attribues of that URL. Those attributes include things like its title (which is almost always the <title> from an HTML document), its MD5 hash, and the date it was added to the Connotea database. A full list of the attributes available is given below.

A post is what a user does with a bookmark -- it represents a bookmarking event. As such, it has attributes like the name of the user, the tags the user assigned, the date they created it and whether it is private or not. Again, a full list is given below.

In other words, a bookmark may belong to many users, but a post can only belong to one.

Libraries and Sample Code

The quickest way to get started wth the API is to download one of the wrapper libraries and accompanying sample code. These will give you an idea of what is possible with the API, and of how to write applications that use it. Libraries are currently available in Perl, Python, and Ruby. For full details on how the Web API works, read on.

Request Parameters

Web API queries are constructed using a combination of the following filtering criteria. All queries must contain at least one of the highlighted filters. Note that these are not necessarily used as standard URL query string parameters -- see later for how to contruct a full query URL.

user => for specifying a Connotea user to filter on
tag => for specifying a tag name
date => for specifying a date
uri => for specifying a URL (or an MD5 hash of a URL)
num => the number of results to return (the default is 1000, the maximum is 1000)
start => the result number to start at -- useful for paging through result sets that exceed the maximum num.
q => a string to use as a free-text search within the various attributes of bookmarks and posts.

Authentication

The API uses Basic HTTP authentication, your username and password being the same as your standard Connotea account. The realm is 'Connotea'.

All API requests require authentication (see WebAPIAuthentication).

In order to validate your username and password, you can do an

HTTP GET

for

http://www.connotea.org/data/noop

This, as the URL suggests, has no effect, but will challenge you for your credentials and return 200 OK if they are valid.

How to Retrieve Data from Connotea

All API operations are standard HTTP requests. To retrieve information, you just GET the relevant URL. URLs are constructed as follows:

Request URL Structure

The base URL for all API operations is

http://www.connotea.org/data

This is followed by an indicator of the type of data you want, followed by the user, tag and uri filters in a defined order, after which come the search, number and start parameters, which can appear in any order.

Specifically, construct the URL like this:

http://www.connotea.org/data
 
  /bookmarks or /tags or '' (empty string, which means 'posts') 
  /user/ [username]
  /tag/ [tagname]
  /date/ [date of form YYYY-MM-DD ]
  /uri/ [uri or hash]
  ?
  q= [free text search string]
  &
  num= [number of results per]
  &
  start= [result number to start at]

For example, to retrieve a list of all the tags that user 'harrytruman' has used, GET the following URL:

http://www.connotea.org/data/tags/user/harrytruman

Or to get all the tags used on http://www.google.com/, GET the following:

http://www.connotea.org/data/tags/uri/http://www.google.com/

Or to get all the posts (i.e. bookmarking events) for http://www.google.com/:

http://www.connotea.org/data/uri/http://www.google.com/

Or to get all the bookmarks (i.e. URLs) that have had the tag readme assigned to them (by any user):

http://www.connotea.org/data/bookmarks/tag/readme

Or to get all the posts made by user harrytruman, tagged with readme, that match the string bookmarking:

http://www.connotea.org/data/user/harrytruman/tag/readme?q=bookmarking

You get the idea...

Using MD5 Digests

You can use an MD5 hex digest of the URI in place of the raw URI string. For example:

http://www.connotea.org/data/uri/ebff2112ac3fae55abedd8ed2fb73dc0

Results Format

The results of your query come in the body of the HTTP response. The body can be easily parsed as RDF, or just as raw XML if you prefer.

The response for each request type looks a little different:

For Bookmarks

<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
  xmlns:dc="http://purl.org/dc/elements/1.1/"
  xmlns:dcterms="http://purl.org/dc/terms/"
  xmlns:prism="http://prismstandard.org/namespaces/1.2/basic/"
  xmlns:foaf="http://xmlns.com/foaf/0.1/"
  xmlns="http://www.connotea.org/2005/01/schema#"
>

 <dcterms:URI rdf:about=" [ The link out to the original web page. ]">
  <link> [ The link is here too. ] </link>

  <dc:title> [ The Bookmark title -- i.e. the title found in the HTML. ] </dc:title>
 
  <!-- list of tags assigned to this URL by all users who've bookmaeked it -->
  <tag> [ tag 1 ] </tag>
  <tag> [ tag 2 ] </tag>
  <tag> [ ... ] </tag>
  
  <!-- list of all users who posted this bookmark -->    
  <postedBy> [ username 1 ] </postedBy>
  <postedBy> [ username 2 ] </postedBy>
  <postedBy> [ ... ] </postedBy>
  
  <postCount> [ Number of times the bookmark has been posted. ] </postCount>
  <bookmarkID> [ Internal Connotea ID for bookmark, useful for debugging. ] </bookmarkID>
  <hash> [ MD5 hash of the bookmark's URL.  Used as a key by Connoea ] </hash>
  
  <created> [ Date the URL was first added to the database. ] </created>
  <updated> [ Date the bookmark was last updated. ] </updated>
  <firstUser> [ Name of first user to post this bookmark. ] </firstUser>
  
  <!-- If the bookmark is for an article or book that Connotea can get bibliographic information for,
  	      the citation element will be present -->
   
  <citation>
   <rdf:Description>
    <prism:title>[  Title of the reference.  This may be different to dc:title above. ] </prism:title>
        
    <!-- list of authors -->
    <foaf:maker>
     <foaf:Person>
      <foaf:name> [ Name of author 1 ] </foaf:name>
     </foaf:Person>
    </foaf:maker>
        
    <foaf:maker>
     <foaf:Person>
      <foaf:name> [ Name of author 2 ] </foaf:name>
     </foaf:Person>
    </foaf:maker>
        
    [  ...etc. ]
    
    <dc:date> [ Publication date for the reference. ] </dc:date>
    <prism:publicationName>
     [ Name of publication the article appeared in -- i.e the journal name. ]
    </prism:publicationName>
    <prism:issn >[ ISSN of publication. ] </prism:issn>
    
    <doiResolver rdf:resource=" [ If the article has a DOI, the dx.oi.org link will appear here. ] " />
    <dc:identifier>[The DOI in the form doi:xx.xxxx/xxxxxx ] </dc:identifier>
     
    <pmidResolver rdf:resource=" [ If the article has a Pubmed ID,
    	      		       	      	      	  a link to its entry in the Pubmed database
    						  will appear here. ] " />
    <dc:identifier> [ The Pubmed ID in the form PMID: xxxxxxxx ] </dc:identifier>
   </rdf:Description>
  </citation>
 </dcterms:URI>
  
 <dcterms:URI>
 
  [ ...etc. ]
 
 </dcterms:URI>
     
</rdf:RDF>

For Posts

<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
  xmlns:dc="http://purl.org/dc/elements/1.1/"
  xmlns:dcterms="http://purl.org/dc/terms/"
  xmlns:prism="http://prismstandard.org/namespaces/1.2/basic/"
  xmlns:foaf="http://xmlns.com/foaf/0.1/"
  xmlns="http://www.connotea.org/2005/01/schema#"
>

<Post rdf:about="[ URL of this post on Connotea ]">
 <title> [ The title the user gave to the post.
 	       	   This may be different to the bookmark title and the citation title. ] </title>

 <!-- A list of tags that this user assigned to thir post -->
 <dc:subject> [ tag 1 ] </dc:subject>
 <dc:subject> [ tag 2 ] </dc:subject>
 <dc:subject> [ ... ] </dc:subject>
  
 <userBookmarkID>[ Internal Connotea ID  for this post, useful for debugging. ]</userBookmarkID>
 
 <dc:creator>[ Name of user who created this post. ] </dc:creator>
 
 <private> [ Privacy status: 1 = private, 0 = public ] </private>
 <created> [ Date this post was created. ] </created>
 <updated> [ Date this post was last updated. ] </updated>
 <comment>
  <rdf:Description>
   <entry>
    [ Comment text. ] 
   </entry>
   <created> [ Date the comment was created. ] </created>
   <updated> [ Date the comment was last updated. ] </updated>
  </rdf:Description>
 </comment>
 
 <uri>
  <!-- the contents of the uri element are almost identical to the bookmark format described above -->
  
  <dcterms:URI rdf:about=" [ The link out to the original webpage. ] ">
   <dc:title> [ The bookmark title, as distinct from the user's personal title for the post. ] </dc:title>
   <link> [ Again, the link out to the orginial web page. ] </link>
   <hash> [ MD5 hash of the link. ] </hash>
   
   <!-- If the bookmark is for an article or book that Connotea can get bibliographic information for,
   	       the citation element will be present -->
   <citation>
    <rdf:Description>
     <prism:title> [  Title of the reference.  This may be different to the dc:title above. ] </prism:title>
            
     <!-- list of authors -->
     <foaf:maker>
      <foaf:Person>
       <foaf:name> [Name of author 1. ] </foaf:name>
      </foaf:Person>
     </foaf:maker>
            
     <foaf:maker>
      <foaf:Person>
       <foaf:name> [ Name of author 2. ] </foaf:name>
      </foaf:Person>
     </foaf:maker>
            
     [  ...etc. ]
     
     <dc:date> [ Publication date for the reference. ] </dc:date>
     <prism:publicationName> [ Name of publication the article appeared in
                                                  -- i.e the journal name. ] </prism:publicationName>
     <prism:issn> [ ISSN of publication. ] </prism:issn>
     <doiResolver rdf:resource=" [ If the article has a DOI, the dx.oi.org link will appear here. ] " />
     <dc:identifier> [ The DOI in the form doi:xx.xxxx/xxxxxx ] </dc:identifier>
      	 
     <pmidResolver rdf:resource=" [ If the article has a Pubmed ID,
                                                        a link to its entry in the Pubmed
                                                         database will appear here. ]  " />
     <dc:identifier> [ The Pubmed ID in the form PMID: xxxxxxxx ] </dc:identifier>
    </rdf:Description>
   </citation>
        
  </dcterms:URI>
 </uri>
</Post>

<Post>

 [ ...etc. ]
 
</Post>
    
</rdf:RDF>

For Tags

<?xml version="1.0"?>
<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns="http://www.connotea.org/2005/01/schema#"
>
 <TagList rdf:about=" [ Your request URL is echoed here. ] "> 
  <item>
   <Tag>
    <rdf:value> [ First tag. ] </rdf:value>
    <postCount> [ The number of times this tag has been used. ] </postCount>
    <usageScore> [ The usage score for this tag.
                                This takes account of how recently it was used, as well as how often. ] </usageScore>
   </Tag>
  </item>
    
  <item>
   <Tag>
    <rdf:value> [ Second tag. ] </rdf:value>
    <postCount> [ Count for second tag. ] </postCount>
    <usageScore> [ Usage score for second tag. ] </usageScore>
   </Tag>
  </item>
      
   [ ...etc. ]
      
 </TagList>
</rdf:RDF>

How to Create a New Post / Bookmark

New posts can be created by submitting an HTTP POST request to

http://www.connotea.org/data/add

The body of the POST should be simply an HTML form-style set of key=value URL-escaped pairs.

The fields available are listed below. The uri and tags fields are required, alll other fields are optional.

uri => the URL for the bookmark you're creating
tags => a string representing the tags. Individual tags should be comma- or space-separated, and multi-word tags must be enclosed in quotes ("")
usertitle => the title to use for the post
description => description of the bookmark
mywork => 0 or 1. If 1, it means you are claiming authorship (or co-authorship) of the work being bookmarked
private => 0 or 1. 0 means the post is shared with all, 1 means it is kept private to the user.
comment => HTML for a comment. Note that newlines will be automatically converted to <br/>.

For example, to add the link 'http://www.nature.com/nature/' to your collection under the tags 'Nature' and 'Science Journal', you should submit the following:

uri=http%3A%2F%2Fwww.nature.com%2Fnature%2F&tags=Nature%20%22Science%20Journal%22

If all goes well, Connotea will respond with a 201 Created status code, and the location of the new post will be given in the Location: header. Other status codes indicate an error -- the reason for the error will be given in the body of the HTTP reponse (see below).

How to edit an existing post

Editing a post works very much like creating a post -- you have to POST a key=value list of the changes you want to make.

The URL to POST to is

http://www.connotea.org/data/edit

The same parameters are available, but an important thing to note is that for any field you don't wish to change you should either:

omit that parameter altogther or
include the value that you wish to keep.

Note: If a parameter is present, but has no value, that field will be reset in the database.

For example, consider a post that looks like the following:

Title => A Great New Article About Something
URL => http://www.example.org/article1
Description => This is really very interesting
Tags => readme, "interesting something"

In order to edit the tags (to remove the readme, say), you would issue the following request.

POST

http://www.connotea.org/data/edit

with the body

uri=http://www.examlpe.org/article1
&
tags="interesting something"

Note: this should in fact be URL escaped, I'm leaving it unescaped here for clarity

However, if you were to issue the following request instead:

uri=http://www.examlpe.org/article1
&
tags="interesting something"
&
description=
&
usertitle=
&
lastcomment=

Then both the description and title would be set to empty strings, and the last comment made would be deleted.

If successful, Connotea will respond with a 201 Created staus code. otherwise, error messages will be given in the body of the HTTP response (see below).

How to remove a post

To remove a post from your collection, simply issue an HTTP POST request to

http://www.connotea.org/data/remove

with the uri parameter in the body. For example, to totally remove the above post use the following body:

uri=http://www.examlpe.org/article1

Again, this should be url escaped.

If successful, Connotea will respond with a 200 OK staus code. otherwise, error messages will be given in the body of the HTTP response (see below).

Error Messages

All add, edit and remove requests are answered with a Response document:

<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns="http://www.connotea.org/2005/01/schema#"
>
 <Response rdf:about="">
  <code>[ HTTP response code will be echoed here ]</code>
  <message>[ A nice plain text message to pass on to the user ]</message>
  <isSuccess>1</isSuccess>
  <!-- or -->
  <isFailure>1</isFailure> <!-- Note that only one of either
                                           isSuccess or isFailure will be present -->
  <user>[ the name of the user making the request ]</user>
 </Response>

</rdf:RDF>

You would normally only need to look inside this document if your request was unsuccessful. The HTTP response code is echoed in the <code> element, and there will be either an <isSuccess> or <isFailure> element as appropriate. A human-readable message explaining the problem can be found in the <message> element.

Gotchas

Something happened that you weren't expecting?

You edited a post, and then all the other fields disappeared

You almost certainly included dangling paramerters in your submission. See the section on editing above.

Another posibility is that you POSTed to data/add, not data/edit. Note that data/add can be used to edit a post, but there's a crucial difference -- it will totally overwrite the existing post.

You get a '501 Not Implemented' response

If you get a '501 Not Implemented' response then it almost certainly means you've tried to do something that is, well, not implemented yet. You will definitely get this response if you try a query that doesn't include one of the filters highlighted above.

You get no data

Your HTTP client may be timing out. Connotea is not all-powerful, and some large requests may take a long time to calculate, so try increasing the timeout value. Another option would be to reduce the number of results you're asking for in the num= parameter.

Your bookmark didn't change when you tried to edit

Are you sure the URL exists in the Connotea database? data/edit can only be used to edit existing bookmarks -- you must use data/add to create new ones. However, be careful of the differences between add and edit (see above).

You get fewer results than you expected or asked for

There's a limit of 1000 items in the results set, which is enforced even if you specify a higher number in the num= parameter. To get more than 1000 items, you should page through the results using start= parameters.

Further Help

Questions about the Web API and associated libraries should be posted to the connotea-code-devel mailing list.

Edit Page | Page History | Wiki Home Page | Recent Changes | Page List

Version 11 Changes (Current or 10 9 8 7 6 5 4 3 2 1) | Last updated: Tue Aug 07 2007 13:14 UTC by User:martin (sounds better with Perl then Python)