├── LICENSE ├── README.textile ├── facebook_oauth.gemspec └── lib ├── facebook_oauth.rb └── facebook_oauth ├── client.rb └── objects.rb /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) Richard Taylor 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining 4 | a copy of this software and associated documentation files (the 5 | "Software"), to deal in the Software without restriction, including 6 | without limitation the rights to use, copy, modify, merge, publish, 7 | distribute, sublicense, and/or sell copies of the Software, and to 8 | permit persons to whom the Software is furnished to do so, subject to 9 | the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be 12 | included in all copies or substantial portions of the Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 15 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 16 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 17 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 18 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 19 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 20 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.textile: -------------------------------------------------------------------------------- 1 | h1. Facebook OAuth Graph API client library for Ruby 2 | 3 | h2. Install the gem 4 | 5 | sudo gem install facebook_oauth 6 | 7 | h2. Using the gem 8 | 9 | To make authorized requests with the client library you'll need to "create a Facebook Application":http://www.facebook.com/developers/createapp.php. 10 | 11 | See "http://facebook-oauth.heroku.com/":http://facebook-oauth.heroku.com/ for a full integration example. 12 | 13 | h2. Authorized request example 14 | 15 | To use the full power of the Facebook API you need to authorize your application and a valid Facebook user via OAuth. 16 | An example showing how to update the status of an authorized user is below. 17 | 18 | Firstly we need to create an instance of the client with your application client credentials you have been given by Facebook 19 | when you set up your application. 20 | 21 | 
client = FacebookOAuth::Client.new(
22 |     :application_id => 'YOUR_APPLICATION_ID',
23 |     :application_secret => 'YOUR_APP_SECRET_KEY',
24 |     :callback => 'http://example.com/facebook/callback'
25 | )
26 | 
27 | client.authorize_url
28 | => "https://graph.facebook.com/oauth/authorize?scope=SCOPE&client_id=ID&type=web_server&redirect_uri=CALLBACK"
29 |
30 | 31 | In your application your user would be redirected to Facebook to authorize the application at this point. The code continues below assuming the user has authorized your application, facebook will return to your callback URL with a code parameter. 32 | 33 | 
access_token = client.authorize(:code => code)
34 | 
35 | client.me.info # returns your user information
36 |
37 | 38 | Now if you keep hold of the access_token.token (usually in the database) for this user you won't need to re-authorize them next time. When you create an instance of the client you can just pass in the access token that you have stored. 39 | 40 | 
access_token = @user.access_token # assuming @user
41 | 
42 | client = FacebookOAuth::Client.new(
43 |     :application_id => 'YOUR_APPLICATION_ID',
44 |     :application_secret => 'YOUR_APP_SECRET_KEY',
45 |     :token => access_token
46 | )
47 | 
48 | client.me.info # returns your user information
49 |
50 | 51 | h2. Supported objects 52 | 53 | * Me (a special object that represents the current authorized user) 54 | 55 | * Album 56 | * Event 57 | * Group 58 | * Link 59 | * Note 60 | * Page 61 | * Photo 62 | * Post 63 | * Status 64 | * User 65 | * Video 66 | 67 | You can access any object listed above in the same way via the API. For example: 68 | 69 | 
client.me.home    # the authorized users news feed
70 | client.event('event_id').attending    # event attendees
71 | client.group('group_id').members    # group members
72 | client.photo('photo_id').comments  # comments on a photo
73 |
74 | 75 | Check out the "Facebook API Reference":http://developers.facebook.com/docs/reference/api/ to see what methods are available. 76 | 77 | h2. Publishing options 78 | 79 | In order to publish content to a user you need to have the correct permissions. For example, to publish to a users wall you need the publish_stream permission. You specify the permissions you want to have for the authorizing user when you generate the authorize url like this: 80 | 81 | 
client.authorize_url(:scope => 'publish_stream')
82 | 83 | The scope is a comma-separated list of permissions. See the "Facebook Permissions Documentation":http://developers.facebook.com/docs/authentication/permissions for more information. 84 | 85 | With the correct permissions you can now post to a users wall like this: 86 | 87 | 
client.me.feed(:create, :message => 'Testing writing to your wall...')
88 | 89 | Other examples include: 90 | 91 | 
client.event('event_id').attending(:create) # the user is attending the event
92 | client.post('post_id').comments(:create, :message => 'my comment') # comment on a post
93 | client.user('user_id').albums(:create, :name => 'my album', :message => 'cool pictures') # create an album
94 |
95 | 96 | For a full list of supported publishing objects and parameters check out the "Facebook API Documentation":http://developers.facebook.com/docs/api under "Publishing to Facebook." 97 | 98 | NOTE: I still have to implement the upload a photo method. Also if you can think of a better syntax for the create methods let me know! -------------------------------------------------------------------------------- /facebook_oauth.gemspec: -------------------------------------------------------------------------------- 1 | # -*- encoding: utf-8 -*- 2 | 3 | Gem::Specification.new do |s| 4 | s.name = %q{facebook_oauth} 5 | s.version = "0.3.0" 6 | 7 | s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version= 8 | s.authors = ["Richard Taylor"] 9 | s.date = %q{2011-11-03} 10 | s.description = %q{facebook_oauth is a Ruby client library for the Facebook OAuth Graph API} 11 | s.email = %q{moomerman@gmail.com} 12 | s.files = ["LICENSE", "README.textile","lib/facebook_oauth.rb"] + Dir.glob('lib/facebook_oauth/*.rb') 13 | s.has_rdoc = false 14 | s.homepage = %q{http://github.com/moomerman/facebook_oauth} 15 | s.rdoc_options = ["--inline-source", "--charset=UTF-8"] 16 | s.require_paths = ["lib"] 17 | s.rubyforge_project = %q{facebook_oauth} 18 | s.rubygems_version = %q{1.3.1} 19 | s.summary = %q{facebook_oauth is a Ruby client library for the Facebook OAuth Graph API} 20 | 21 | if s.respond_to? :specification_version then 22 | current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION 23 | s.specification_version = 2 24 | 25 | if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then 26 | s.add_runtime_dependency(%q, [">= 0.5.1"]) 27 | s.add_runtime_dependency(%q, [">= 1.5.3"]) 28 | s.add_runtime_dependency(%q, [">= 1.16"]) 29 | %w(shoulda mocha).each do |dep| 30 | s.add_development_dependency dep 31 | end 32 | else 33 | s.add_dependency(%q, [">= 0.5.1"]) 34 | s.add_dependency(%q, [">= 1.5.3"]) 35 | s.add_dependency(%q, [">= 1.16"]) 36 | end 37 | else 38 | s.add_dependency(%q, [">= 0.5.1"]) 39 | s.add_dependency(%q, [">= 1.5.3"]) 40 | s.add_dependency(%q, [">= 1.16"]) 41 | end 42 | end 43 | -------------------------------------------------------------------------------- /lib/facebook_oauth.rb: -------------------------------------------------------------------------------- 1 | require 'oauth2' 2 | require 'json' 3 | require 'mime/types' 4 | 5 | require 'facebook_oauth/client' 6 | 7 | module FacebookOAuth 8 | end -------------------------------------------------------------------------------- /lib/facebook_oauth/client.rb: -------------------------------------------------------------------------------- 1 | require 'facebook_oauth/objects' 2 | 3 | module FacebookOAuth 4 | class Client 5 | 6 | def initialize(options = {}) 7 | @application_id = options[:application_id] 8 | @application_secret = options[:application_secret] 9 | @callback = options[:callback] 10 | @token = options[:token] 11 | end 12 | 13 | def authorize_url(options = {}) 14 | options[:scope] ||= 'offline_access,publish_stream' 15 | client.auth_code.authorize_url( 16 | :client_id => @application_id, 17 | :redirect_uri => options[:callback] || @callback, 18 | :scope => options[:scope] 19 | ) 20 | end 21 | 22 | def authorize(options = {}) 23 | @access_token ||= client.auth_code.get_token( 24 | options[:code], 25 | :redirect_uri => options[:callback] || @callback, 26 | :parse => :query 27 | ) 28 | 29 | @token = @access_token.token 30 | @access_token 31 | end 32 | 33 | private 34 | def client 35 | @client ||= OAuth2::Client.new( 36 | @application_id, 37 | @application_secret, 38 | { :site=>"https://graph.facebook.com", :token_url => "/oauth/access_token" } 39 | ) 40 | end 41 | 42 | def access_token 43 | @access_token ||= OAuth2::AccessToken.new(client, @token) 44 | @access_token.options[:mode] = :query 45 | @access_token.options[:param_name] = :access_token 46 | @access_token 47 | end 48 | 49 | def _get(url) 50 | oauth_response = access_token.get(url).parsed 51 | JSON.parse(oauth_response) rescue oauth_response 52 | end 53 | 54 | def _post(url, params={}, headers={}) 55 | oauth_response = access_token.post(url, :params => params, :headers => headers).parsed 56 | puts oauth_response.inspect 57 | JSON.parse(oauth_response) rescue oauth_response 58 | end 59 | 60 | def _delete(url) 61 | oauth_response = access_token.delete(url).parsed 62 | JSON.parse(oauth_response) rescue oauth_response 63 | end 64 | end 65 | end 66 | 67 | -------------------------------------------------------------------------------- /lib/facebook_oauth/objects.rb: -------------------------------------------------------------------------------- 1 | module FacebookOAuth 2 | class Client 3 | 4 | def me(id = 'me') 5 | FacebookOAuth::FacebookObject.new(id, self) 6 | end 7 | 8 | def album(id) 9 | FacebookOAuth::FacebookObject.new(id, self) 10 | end 11 | 12 | def event(id) 13 | FacebookOAuth::FacebookObject.new(id, self) 14 | end 15 | 16 | def group(id) 17 | FacebookOAuth::FacebookObject.new(id, self) 18 | end 19 | 20 | def link(id) 21 | FacebookOAuth::FacebookObject.new(id, self) 22 | end 23 | 24 | def note(id) 25 | FacebookOAuth::FacebookObject.new(id, self) 26 | end 27 | 28 | def page(id) 29 | FacebookOAuth::FacebookObject.new(id, self) 30 | end 31 | 32 | def photo(id) 33 | FacebookOAuth::FacebookObject.new(id, self) 34 | end 35 | 36 | def post(id) 37 | FacebookOAuth::FacebookObject.new(id, self) 38 | end 39 | 40 | def status(id) 41 | FacebookOAuth::FacebookObject.new(id, self) 42 | end 43 | 44 | def user(id) 45 | FacebookOAuth::FacebookObject.new(id, self) 46 | end 47 | 48 | def video(id) 49 | FacebookOAuth::FacebookObject.new(id, self) 50 | end 51 | 52 | end 53 | 54 | class FacebookObject 55 | def initialize(oid, client) 56 | @oid = oid 57 | @client = client 58 | end 59 | 60 | def info 61 | @client.send(:_get, @oid) 62 | end 63 | 64 | def method_missing(method, *args) 65 | first = args.shift 66 | params = args.first || {} 67 | 68 | if first and first == :create 69 | @client.send(:_post, "/#{@oid}/#{method.to_s}", params) 70 | else 71 | @client.send(:_get, "/#{@oid}/#{method.to_s}") 72 | end 73 | end 74 | 75 | end 76 | end --------------------------------------------------------------------------------