koala 1.1.0rc3 → 1.1.0
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGELOG +1 -0
- data/Gemfile +4 -0
- data/koala.gemspec +2 -2
- data/readme.md +33 -26
- data/spec/spec_helper.rb +2 -1
- data/spec/support/json_testing_fix.rb +18 -0
- metadata +6 -4
data/CHANGELOG
CHANGED
@@ -13,6 +13,7 @@ Updated methods:
|
|
13
13
|
-- Filename can now be specified when uploading (e.g. for Ads API) (thanks, sshilo!)
|
14
14
|
-- get_objects([]) returns [] instead of a Facebook error in non-batch mode (thanks, aselder!)
|
15
15
|
Internal improvements:
|
16
|
+
-- Koala is now more compatible with other Rubies (JRuby, Rubinius, etc.)
|
16
17
|
-- HTTP services are more modular and can be changed on the fly (thanks, chadk!)
|
17
18
|
-- Includes support for uploading StringIOs and other non-files via Net::HTTP even when using TyphoeusService
|
18
19
|
-- Koala now uses multi_json to improve compatibility with Rubinius and other Ruby versions
|
data/Gemfile
CHANGED
data/koala.gemspec
CHANGED
@@ -2,8 +2,8 @@
|
|
2
2
|
|
3
3
|
Gem::Specification.new do |s|
|
4
4
|
s.name = %q{koala}
|
5
|
-
s.version = "1.1.
|
6
|
-
s.date = %q{2011-
|
5
|
+
s.version = "1.1.0"
|
6
|
+
s.date = %q{2011-07-18}
|
7
7
|
|
8
8
|
s.summary = %q{A lightweight, flexible library for Facebook with support for the Graph API, the REST API, realtime updates, and OAuth authentication.}
|
9
9
|
s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook. It allows read/write access to the social graph via the Graph and REST APIs, as well as support for realtime updates and OAuth and Facebook Connect authentication. Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services.}
|
data/readme.md
CHANGED
@@ -4,7 +4,7 @@ Koala
|
|
4
4
|
|
5
5
|
* Lightweight: Koala should be as light and simple as Facebook’s own new libraries, providing API accessors and returning simple JSON. (We clock in, with comments, at just over 750 lines of code.)
|
6
6
|
* Fast: Koala should, out of the box, be quick. In addition to supporting the vanilla Ruby networking libraries, it natively supports Typhoeus, our preferred gem for making fast HTTP requests. Of course, that brings us to our next topic:
|
7
|
-
* Flexible: Koala should be useful to everyone, regardless of their current configuration. (
|
7
|
+
* Flexible: Koala should be useful to everyone, regardless of their current configuration. (In addition to vanilla Ruby, we support JRuby, Rubinius, and REE, and provide built-in mechanism for using whichever HTTP library you prefer.)
|
8
8
|
* Tested: Koala should have complete test coverage, so you can rely on it. (Our complete test coverage can be run against either mocked responses or the live Facebook servers.)
|
9
9
|
|
10
10
|
Installation
|
@@ -13,28 +13,26 @@ Installation
|
|
13
13
|
Easy:
|
14
14
|
|
15
15
|
[sudo|rvm] gem install koala
|
16
|
-
# for 1.1rc add --pre
|
17
16
|
|
18
|
-
|
19
17
|
Or in Bundler:
|
20
18
|
|
21
|
-
gem "koala"
|
19
|
+
gem "koala"
|
22
20
|
|
23
21
|
Graph API
|
24
22
|
----
|
25
23
|
The Graph API is the simple, slick new interface to Facebook's data. Using it with Koala is quite straightforward:
|
26
24
|
|
27
|
-
graph = Koala::Facebook::GraphAPI.new(oauth_access_token)
|
28
|
-
profile = graph.get_object("me")
|
29
|
-
friends = graph.get_connections("me", "friends")
|
30
|
-
graph.put_object("me", "feed", :message => "I am writing on my wall!")
|
25
|
+
@graph = Koala::Facebook::GraphAPI.new(oauth_access_token)
|
26
|
+
profile = @graph.get_object("me")
|
27
|
+
friends = @graph.get_connections("me", "friends")
|
28
|
+
@graph.put_object("me", "feed", :message => "I am writing on my wall!")
|
31
29
|
|
32
30
|
The response of most requests is the JSON data returned from the Facebook servers as a Hash.
|
33
31
|
|
34
32
|
When retrieving data that returns an array of results (for example, when calling GraphAPI#get_connections or GraphAPI#search) a GraphCollection object (a sub-class of Array) will be returned, which contains added methods for getting the next and previous page of results:
|
35
33
|
|
36
34
|
# Returns the feed items for the currently logged-in user as a GraphCollection
|
37
|
-
feed = graph.get_connections("me", "feed")
|
35
|
+
feed = @graph.get_connections("me", "feed")
|
38
36
|
|
39
37
|
# GraphCollection is a sub-class of Array, so you can use it as a usual Array
|
40
38
|
first_entry = feed[0]
|
@@ -48,28 +46,28 @@ When retrieving data that returns an array of results (for example, when calling
|
|
48
46
|
next_path, next_args = feed.next_page_params
|
49
47
|
|
50
48
|
# You can use those params to easily get the next (or previous) page
|
51
|
-
page = graph.get_page(feed.next_page_params)
|
49
|
+
page = @graph.get_page(feed.next_page_params)
|
52
50
|
|
53
51
|
You can make multiple calls at once using Facebook's batch API:
|
54
52
|
|
55
53
|
# Returns an array of results as if they were called non-batch
|
56
|
-
graph.batch do
|
57
|
-
|
58
|
-
|
59
|
-
graph.get_picture('me')
|
54
|
+
@graph.batch do |batch_api|
|
55
|
+
batch_api.get_object('me')
|
56
|
+
batch_api.get_object('koppel')
|
60
57
|
end
|
61
58
|
|
62
59
|
Check out the wiki for more examples.
|
63
60
|
|
64
|
-
The
|
61
|
+
The REST API
|
65
62
|
-----
|
66
63
|
Where the Graph API and the old REST API overlap, you should choose the Graph API. Unfortunately, that overlap is far from complete, and there are many important API calls that can't yet be done via the Graph.
|
67
64
|
|
68
65
|
Koala now supports the old-school REST API using OAuth access tokens; to use this, instantiate your class using the RestAPI class:
|
69
66
|
|
70
|
-
|
71
|
-
|
72
|
-
|
67
|
+
@rest = Koala::Facebook::RestAPI.new(oauth_access_token)
|
68
|
+
@rest.fql_query(my_fql_query) # convenience method
|
69
|
+
@rest.fql_multiquery(fql_query_hash) # convenience method
|
70
|
+
@rest.rest_call("stream.publish", arguments_hash) # generic version
|
73
71
|
|
74
72
|
We reserve the right to expand the built-in REST API coverage to additional convenience methods in the future, depending on how fast Facebook moves to fill in the gaps.
|
75
73
|
|
@@ -82,7 +80,7 @@ You can use the Graph and REST APIs without an OAuth access token, but the real
|
|
82
80
|
|
83
81
|
If your application uses Koala and the Facebook [JavaScript SDK](http://github.com/facebook/connect-js) (formerly Facebook Connect), you can use the OAuth class to parse the cookies:
|
84
82
|
@oauth.get_user_from_cookies(cookies) # gets the user's ID
|
85
|
-
|
83
|
+
@oauth.get_user_info_from_cookies(cookies) # parses and returns the entire hash
|
86
84
|
|
87
85
|
And if you have to use the more complicated [redirect-based OAuth process](http://developers.facebook.com/docs/authentication/), Koala helps out there, too:
|
88
86
|
# generate authenticating URL
|
@@ -93,20 +91,18 @@ And if you have to use the more complicated [redirect-based OAuth process](http:
|
|
93
91
|
You can also get your application's own access token, which can be used without a user session for subscriptions and certain other requests:
|
94
92
|
@oauth.get_app_access_token
|
95
93
|
|
96
|
-
|
97
|
-
|
98
|
-
*Signed Requests:* Excited to try out the new signed request authentication scheme? Good news! Koala now supports parsing those parameters:
|
94
|
+
For those building apps on Facebook, parsing signed requests is simple:
|
99
95
|
@oauth.parse_signed_request(request)
|
100
96
|
|
101
|
-
|
97
|
+
Or, if for some horrible reason, you're still using session keys, despair not! It's easy to turn them into shiny, modern OAuth tokens:
|
102
98
|
@oauth.get_token_from_session_key(session_key)
|
103
99
|
@oauth.get_tokens_from_session_keys(array_of_session_keys)
|
104
100
|
|
101
|
+
That's it! It's pretty simple once you get the hang of it. If you're new to OAuth, though, check out the wiki and the OAuth Playground example site (see below).
|
102
|
+
|
105
103
|
Real-time Updates
|
106
104
|
-----
|
107
|
-
The Graph API
|
108
|
-
|
109
|
-
Currently, Facebook only supports subscribing to users, permissions and errors. On top of that, there are limitations on what attributes and connections for each of these objects you can subscribe to updates for. Check the [official Facebook documentation](http://developers.facebook.com/docs/api/realtime) for more details.
|
105
|
+
Sometimes, reaching out to Facebook is a pain -- let it reach out to you instead. The Graph API allows your application to subscribe to real-time updates for certain objects in the graph; check the [official Facebook documentation](http://developers.facebook.com/docs/api/realtime) for more details on what objects you can subscribe to and what limitations may apply.
|
110
106
|
|
111
107
|
Koala makes it easy to interact with your applications using the RealtimeUpdates class:
|
112
108
|
|
@@ -130,6 +126,17 @@ And to top it all off, RealtimeUpdates provides a static method to respond to Fa
|
|
130
126
|
|
131
127
|
For more information about meet_challenge and the RealtimeUpdates class, check out the Real-Time Updates page on the wiki.
|
132
128
|
|
129
|
+
Test Users
|
130
|
+
-----
|
131
|
+
|
132
|
+
We also support the test users API, allowing you to conjure up fake users and command them to do your bidding using the Graph or REST API:
|
133
|
+
|
134
|
+
@test_users = Koala::Facebook::TestUsers.new(:app_id => id, :secret => secret)
|
135
|
+
user = @test_users.create(is_app_installed, desired_permissions)
|
136
|
+
user_graph_api = Koala::Facebook::GraphAPI.new(user["access_token"])
|
137
|
+
# or, if you want to make a whole community:
|
138
|
+
@test_users.create_network(network_size, is_app_installed, common_permissions)
|
139
|
+
|
133
140
|
See examples, ask questions
|
134
141
|
-----
|
135
142
|
Some resources to help you as you play with Koala and the Graph API:
|
data/spec/spec_helper.rb
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
begin
|
2
2
|
require 'bundler/setup'
|
3
3
|
rescue LoadError
|
4
|
-
puts '
|
4
|
+
puts 'Although not required, bundler is recommended for running the tests.'
|
5
5
|
end
|
6
6
|
|
7
7
|
# load the libraries
|
@@ -9,6 +9,7 @@ require 'koala'
|
|
9
9
|
|
10
10
|
# load testing data libraries
|
11
11
|
require 'support/live_testing_data_helper'
|
12
|
+
require 'support/json_testing_fix' # ensure consistent to_json behavior
|
12
13
|
require 'support/mock_http_service'
|
13
14
|
require 'support/rest_api_shared_examples'
|
14
15
|
require 'support/graph_api_shared_examples'
|
@@ -0,0 +1,18 @@
|
|
1
|
+
# when testing across Ruby versions, we found that JSON string creation inconsistently ordered keys
|
2
|
+
# which is a problem because our mock testing service ultimately matches strings to see if requests are mocked
|
3
|
+
# this fix solves that problem by ensuring all hashes are created with a consistent key order every time
|
4
|
+
|
5
|
+
module MultiJson
|
6
|
+
self.engine = :ok_json
|
7
|
+
|
8
|
+
def encode_with_ordering(object)
|
9
|
+
# if it's a hash, recreate it with k/v pairs inserted in sorted-by-key order
|
10
|
+
# (for some reason, REE 1.8.7 fails if we don't assign the ternary result as a local variable
|
11
|
+
# separate from calling encode_original)
|
12
|
+
new_object = object.is_a?(Hash) ? object.keys.sort.inject({}) {|hash, k| hash[k] = object[k]; hash} : object
|
13
|
+
encode_original(new_object)
|
14
|
+
end
|
15
|
+
|
16
|
+
alias_method :encode_original, :encode
|
17
|
+
alias_method :encode, :encode_with_ordering
|
18
|
+
end
|
metadata
CHANGED
@@ -1,8 +1,8 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: koala
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
prerelease:
|
5
|
-
version: 1.1.
|
4
|
+
prerelease:
|
5
|
+
version: 1.1.0
|
6
6
|
platform: ruby
|
7
7
|
authors:
|
8
8
|
- Alex Koppel, Chris Baclig, Rafi Jacoby, Context Optional
|
@@ -10,7 +10,7 @@ autorequire:
|
|
10
10
|
bindir: bin
|
11
11
|
cert_chain: []
|
12
12
|
|
13
|
-
date: 2011-
|
13
|
+
date: 2011-07-18 00:00:00 +02:00
|
14
14
|
default_executable:
|
15
15
|
dependencies:
|
16
16
|
- !ruby/object:Gem::Dependency
|
@@ -121,6 +121,7 @@ files:
|
|
121
121
|
- spec/fixtures/mock_facebook_responses.yml
|
122
122
|
- spec/spec_helper.rb
|
123
123
|
- spec/support/graph_api_shared_examples.rb
|
124
|
+
- spec/support/json_testing_fix.rb
|
124
125
|
- spec/support/live_testing_data_helper.rb
|
125
126
|
- spec/support/mock_http_service.rb
|
126
127
|
- spec/support/rest_api_shared_examples.rb
|
@@ -143,7 +144,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
143
144
|
requirements:
|
144
145
|
- - ">="
|
145
146
|
- !ruby/object:Gem::Version
|
146
|
-
hash:
|
147
|
+
hash: -702788258280667645
|
147
148
|
segments:
|
148
149
|
- 0
|
149
150
|
version: "0"
|
@@ -180,6 +181,7 @@ test_files:
|
|
180
181
|
- spec/fixtures/mock_facebook_responses.yml
|
181
182
|
- spec/spec_helper.rb
|
182
183
|
- spec/support/graph_api_shared_examples.rb
|
184
|
+
- spec/support/json_testing_fix.rb
|
183
185
|
- spec/support/live_testing_data_helper.rb
|
184
186
|
- spec/support/mock_http_service.rb
|
185
187
|
- spec/support/rest_api_shared_examples.rb
|