README.rdoc in monkeyhelper-muddyit_fu-0.1.0 vs README.rdoc in monkeyhelper-muddyit_fu-0.1.1
- old
+ new
@@ -1,22 +1,40 @@
-= muddyit-fu
+= muddyit_fu
+== Installation
+
+sudo gem install muddyit-fu
+
== Getting started
- You need to first get an account a muddy.it and create a site to hold content.
+muddy.it uses oauth to manage it's api access. To access the muddy.it data
+programmatically you will need to register an application. Login and visit :
-== Installation
+http://www.muddy.it/oauth_clients/
- sudo gem install muddyit-fu
+You can register an application here, a callback URI isn't required.
+The 'consumer token' and 'consumer secret' are used to generate a token for
+accessing muddy.it. For further details and an example of how to programatically
+generate a new access token for muddy.it see here :
+
+http://stakeventures.com/articles/2008/02/23/developing-oauth-clients-in-ruby
+
+See the 'Authorising clients using irb' section for a sample irb session.
+
+These details are then used to provide access to the service. The credentials
+can be stored in a yml file, an example of which is provided below.
+
== Example muddyit.yml
----
-access_key_id: "YOUR KEY"
-secret_access_key: "YOUR SECRET"
+ ---
+ consumer_key: "YOUR_CONSUMER_KEY"
+ consumer_secret: "YOUR_CONSUMER_SECRET"
+ access_token: "YOUR_ACCESS_TOKEN"
+ access_token_secret: "YOUR_ACCESS_TOKEN_SECRET"
-== Sites example
+== Retrieving a site
require 'muddyit_fu'
muddyit = Muddyit.new('muddyit.yml')
muddyit.sites.each do |site|
puts "#{site.label} : #{site.token}"
@@ -25,17 +43,19 @@
== Categorisation request
require 'muddyit_fu'
muddyit = Muddyit.new('muddyit.yml')
site = muddyit.sites.first
- site.pages.categorise(:identifier => 'http://news.bbc.co.uk/1/hi/uk_politics/8011321.stm')
+ site.pages.categorise({:identifier => 'http://news.bbc.co.uk/1/hi/uk_politics/8011321.stm'}, {:minium_confidence => 0.2})
== View categorised pages
require 'muddyit_fu'
- muddyit = Muddyit.new(:access_key_id => 'aaaaaaaaaaaaaa',
- :secret_access_key => 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb')
+ muddyit = Muddyit.new(:consumer_key => 'aaa',
+ :consumer_secret => 'bbb',
+ :access_token => 'ccc',
+ :access_token_secret => 'ddd')
site = muddyit.sites.first
site.pages.index do |page|
puts page.content_data.title
page.results.each do |result|
puts result.uri
@@ -43,38 +63,85 @@
end
== View all pages containing 'Gordon Brown'
require 'muddyit_fu'
- muddyit = Muddyit.new(:access_key_id => 'aaaaaaaaaaaaaa',
- :secret_access_key => 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb')
+ muddyit = Muddyit.new('muddyit.yml')
site = muddyit.sites.first
site.pages.find_by_entity('http://dbpedia.org/resource/Gordon_Brown') do |page|
puts page.identifier
end
== Find related entities for 'Gordon Brown'
require 'muddyit_fu'
- muddyit = Muddyit.new(:access_key_id => 'aaaaaaaaaaaaaa',
- :secret_access_key => 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb')
+ muddyit = Muddyit.new('muddyit.yml')
site = muddyit.sites.first
site.pages.related_entities('http://dbpedia.org/resource/Gordon_Brown').each do |entity|
puts "#{entity.uri} : #{entity.confidence}"
end
== Find related content for : http://news.bbc.co.uk/1/hi/uk_politics/7878418.stm
require 'muddyit_fu'
- muddyit = Muddyit.new(:access_key_id => 'aaaaaaaaaaaaaa',
- :secret_access_key => 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb')
+ muddyit = Muddyit.new('muddyit.yml')
site = muddyit.sites.first
page = site.pages.find('http://news.bbc.co.uk/1/hi/uk_politics/7878418.stm')
puts "Our page : #{page.content_data.title}\n\n"
page.related_content.each do |results|
puts "#{results[:page].content_data.title} #{results[:count]}"
end
+== Authorising clients using irb
+
+ robl@fry:~/$ irb
+ irb(main):002:0> require 'rubygems'
+ => true
+ irb(main):003:0> require 'oauth'
+ => true
+ irb(main):004:0> require 'oauth/consumer'
+ => false
+ irb(main):005:0> @consumer=OAuth::Consumer.new "yourtoken", "yoursecret", {:site => 'http://www.muddy.it' }
+ => #<OAuth::Consumer:0xb7683b7c @key="yourtoken", @secret="yoursecret", @options={:oauth_version=>"1.0",
+ :signature_method=>"HMAC-SHA1", :request_token_path=>"/oauth/request_token",
+ :site=>"http://www.muddy.it", :scheme=>:header,
+ :authorize_path=>"/oauth/authorize", :access_token_path=>"/oauth/access_token",
+ :http_method=>:post}>
+ irb(main):006:0> @request_token=@consumer.get_request_token
+ => #<OAuth::RequestToken:0xb76778e0 @consumer=#<OAuth::Consumer:0xb7683b7c @key="tokenkey",
+ @http=#<Net::HTTP www.muddy.it:80 open=false>, @http_method=:post,
+ @secret="tokensecret", @options={:oauth_version=>"1.0", :signature_method=>"HMAC-SHA1",
+ :request_token_path=>"/oauth/request_token", :site=>"http://www.muddy.it",
+ :scheme=>:header, :authorize_path=>"/oauth/authorize", :access_token_path=>"/oauth/access_token",
+ :http_method=>:post}>, @token="tokenkey", @secret="tokensecret">
+ irb(main):007:0> @request_token.authorize_url
+ => "http://www.muddy.it/oauth/authorize?oauth_token=tokenkey"
+
+To authorise the application, visit the URL, check the 'authorize access' box and
+save. The request token can now be exchanged for an access token :
+
+ irb(main):008:0> @access_token=@request_token.get_access_token
+ => #<OAuth::AccessToken:0xb7667c10 @consumer=#<OAuth::Consumer:0xb7683b7c @key="accesstoken_key",
+ @http=#<Net::HTTP www.muddy.it:80 open=false>, @http_method=:post,
+ @secret="accesstoken_secret", @options={:oauth_version=>"1.0",
+ :signature_method=>"HMAC-SHA1", :request_token_path=>"/oauth/request_token",
+ :site=>"http://www.muddy.it", :scheme=>:header, :authorize_path=>"/oauth/authorize",
+ :access_token_path=>"/oauth/access_token", :http_method=>:post}>, @token="accesstoken",
+ @secret="accesstoken_secret">
+
+This token can also be used to access the service :
+
+ irb(main):016:0> res = @access_token.get "/sites.json"
+ => #<Net::HTTPOK 200 OK readbody=true>
+ irb(main):017:0> res.body
+ ....
+
+The access token credentials to be used with muddyit_fu are :
+
+ irb(main):011:0> @access_token.token
+ => "sometoken"
+ irb(main):012:0> @access_token.secret
+ => "somesecret"
== Contact
Author: Rob Lee
Email: robl [at] monkeyhelper.com