Ruby Wrapper for the Connotea Web API

The current version is www-connotea-ruby-0.1.

Download from SourceForge.

The README information is copied below.

WWW::Connotea v0.1

Ruby Wrapper for the Connotea Web API
(c) Ben Lund 2006
ben@benlund.co.uk

License

This code is made available under the terms of the GNU General Public License:

http://www.gnu.org/copyleft/gpl.html

About

WWW::Connotea implements the Connotea Web API (http://www.connotea.org/wiki/WebAPI)

All classes are defined in 'lib/www/connotea.rb'.

There are some sample scripts that use this library in 'sample':

• post_something.rb -- adds a bookmark to your library
• remove_it.rb -- deletes the bookmark
• my_tags.rb -- prints a list of all the tags you've used
• related_articles.rb -- implements a very basic related articles algorithm using shared tags

Before any of the sample code will run, you'll need to edit the files and enter
your own Connotea username and passsword

Usage

require 'path/to/www/connotea'

c = WWW::Connotea.new(  :user => 'your_username', :password => 'your_password' )
c.authenticate   ### raises an error if log-in credentials are incorrect

# query and post using the WWW::Connotea object. See class details below

c.posts_for(:tag => 'connotea') do |p|
  puts p.title
end

new_post = WWW::ConnoteaPost.new
post.link = 'http://www.example.com'
post.tags = ['My Examlpe Tag', 'and_another_one']
response = c.create(p)

WWW::Connotea

Methods

new(
		:user => 'username',
		:password => 'password',
   	     	:base => 'http://www.connotea.org/',
		:realm => 'Connotea'
	)

:base and :realm are optional, and need only be specified it you are querying a private instance of Connotea Code.

bookmarks_for( 
			:user => 'name of a connotea user'
			:tag   => 'name of a tag'
			:date  => 'yyyy-mm-dd -- just for posts on a certain date'
			:uri    => 'a URL'
			:hash => 'MD5 hash of URL -- alternative to :uri'
			:q      => 'Search string'
			:num => 'number of results -- default is 1000'
			:start => 'result number to start from'
		) { |b| yield block }

Returns an Array of WWW::ConnoteaBoookmark objects. Will also yield if a block is passed.

All parameters for the query are optional, excepting that there must be at least one parameter that is not :start.

posts_for( 
			:user => 'name of a connotea user'
			:tag   => 'name of a tag'
			:date  => 'yyyy-mm-dd -- just for posts on a certain date'
			:uri    => 'a URL'
			:hash => 'MD5 hash of URL -- alternative to :uri'
			:q      => 'Search string'
			:num => 'number of results -- default is 1000'
			:start => 'result number to start from'
		) { |p| yield block }

Returns an Array of WWW::ConnoteaPost objects. Will also yield if a block is passed.
All parameters for the query are optional, excepting that there must be at least one parameter that is not :start.

tags_for( 
			:user => 'name of a connotea user'
			:tag   => 'name of a tag'
			:date  => 'yyyy-mm-dd -- just for posts on a certain date'
			:uri    => 'a URL'
			:hash => 'MD5 hash of URL -- alternative to :uri'
			:q      => 'Search string'
			:num => 'number of results -- default is 1000'
			:start => 'result number to start from'
		) { |t| yield block }

Returns an Array of WWW::ConnoteaTag objects. Will also yield if a block is passed.
All parameters for the query are optional, excepting that there must be at least one parameter that is not :start.

create(p)

Where p is a WWW::ConnoteaPost object. Creates a new post in your library. The post object must have both a link and at least one tag in the tags Array. Returns a WWW::ConnoteaResponse object.

update(p)

Where p is a WWW::ConnoteaPost object. Whichever of the post's attributes are not nil will be overwritten. Those that are nil will remain unchanged. Returns a WWW::Connotearesponse object.

remove(p)

Where p is a WWW::ConnoteaPost object. removes a post from your library. The post object need only have a link. Returns a WWW::Connotearesponse object.

WWW::ConnoteaBookmark

Represents a bookmark in the Connotea database. A bookmark is any URL that has been added to Connotea.

Attributes

link

The bookmark URL.

title

The raw title for the bookmark. This will mostly have been extracted from the HTML.

tags

An Array of all the tags used on this bookmark by all users. Note that it is an Arrray of Strings, not ConnoteaTag? objects.

posted_by

An Array of names of all the users who have posted this bookmark.

posted_by_count

Same as posted_by.size

hash

The MD5 hash of the URL.

created

The date the URL was first added to the Connotea database.

updated

Date the bookmark was last modified.

first_user

Name of the first user to post this bookmark.

citation

Returns a WWW::ConnoteaCitation object

WWW::ConnoteaPost

Represents an entry in a user's collection.

Attributes

title

The title of the post. Note this is the title the user assigned, so may be differnt from the corresponding bookmark title.

link

The URL of this post's bookmark. Same as bookmark.link.

tags

An Array of the tags assigned by the user who made this post. Note that it is an Arrray of Strings, not ConnoteaTag? objects.

description

The user's description for the post.

user

The name of the user who made this post.

privacy_status

0 if the post if public, 1 if private.

created

Date the post was made.

updated

Date post was last modified.

bookmark

Returns the WWW::ConnoteaBookmark object for this post.

WWW::ConnoteaTag

Represents a tag used in Connotea. Only returned via tags_for() queries.

Attributes

label

The name of the tag.

post_count

The number of times the tag has been used in the context of the current query.

usage_score

The usage score for the tag (in the context of the current query). This takes into account both how often and how recently the tag was used.

WWW::ConnoteaCitation

Represents the citation information for a bookmark. Not all bookmarks will have a citation object -- only those for which Connotea can automatically identify bibliographic information, or which were uploaded to Connotea in an RIS file.

Attributes

title

The article or book title.

authors

An Array of author names.

publication_date

The date the article or book was published.

journal

The name of the journal the article was published in.

volume

The journal volume number

issue

The journal issue number.

start_page

The starting page number for the article

end_page

The ending page number for the article.

doi

The article DOI

pmid

The PubMed ID for the article.

WWW::ConntoeaResponse

Represents a reponse message generated by the Connotea Web API. This will be returned by create, update and remove operations, and if there is an error on any other operation.

Attributes

code

The HTTP status code for this response.

location

If an object has been created, this gives its location.

message

A human readable message explaining an errror.

is_success

Returns 1 if the operation was successful, and nil if not.

user

The name of the user who made the request that lead to this repsponse -- i.e. your username.

api_version

The Connotea Web API version.

bibliotech_version

The version of Connotea Code running the service.