rest-graph 1.7.0 → 1.8.0

data/TODO

@@ -8,3 +8,4 @@
 * error_handler can't be turned off
 * more docs?
 * more examples?
+* em is missing headers options

data/doc/ToC.md

@@ -0,0 +1,10 @@
+
+# rest-graph documentation
+
+## Table of Content
+
+* [Tutorial for the beginners, using Rails 3](tutorial.md)
+* [Overview and Design Concept](design.md)
+* [Picking Dependency](dependency.md)
+* [Testing](test.md)
+* [Working in Rails](rails.md)

data/doc/dependency.md

@@ -0,0 +1,78 @@
+
+# Dependency
+
+## Introduction
+
+Because rest-graph is designed to be lightweight and modular, it should
+depend on as little things as possible, and give people the power to choose
+their preference. rest-graph is depending on at least a HTTP client, and
+optionally depending on a JSON parser if you want to auto-decode the JSON
+from servers. (and `auto_decode` is actually the default.) It might also be
+depending on [Rack][] for some operation, for example,
+`RestGraph#parse_rack_env!` and `RestGraph#parse_cookies!` is using
+`Rack::Utils.parse_query`. For those operations, Rack is needed.
+
+[Rack]: https://github.com/rack/rack
+
+## HTTP client (must pick one)
+
+At the beginning, rest-graph uses [rest-client][], and is a must install
+runtime dependency. Later, the support of [em-http-request][] is added,
+so now you can pick either of them or both of them.
+
+Usually, rest-client is used for synchronized (blocking) operations;
+Contrarily, em-http-request is used for asynchronized (evented) operations.
+
+If you don't know what's the difference between them, just use rest-client.
+It's a lot easier to use, and have been tested more. If you don't know how
+to pick, then you might be already using rest-client.
+
+This is an example of using rest-client:
+
+    data = RestGraph.new.get('me')
+
+This is an example of using em-http-request:
+
+    RestGraph.new.aget('me'){ |data| }
+
+This is using em-http-request, too:
+
+    RestGraph.new.get('me', {}, {:async => true}){ |data| }
+
+[rest-client]: https://github.com/archiloque/rest-client
+[em-http-request]: https://github.com/igrigorik/em-http-request
+
+## JSON parser (optional, but needed by default)
+
+When `auto_decode` is set to true, rest-graph would use a JSON parser to
+parse the JSON and return a Ruby object corresponding to that JSON. The most
+widely used JSON parser is [json][], it has two distributions, one is `json`,
+another one is `json_pure`. The former is written in Ruby and C, the latter
+is purely written in Ruby. They are too widely used so you might want to
+use it on your application, too. But [yajl-ruby][] is a lot more recommended,
+it's... generally better, you can take a look on [yajl-ruby's README][]
+
+rest-graph would first try to use Yajl, if it's not defined, then try JSON.
+If it's not defined either, then it would try to `require 'yajl'`, rescue
+`LoadError`, and `request 'json'`. The latter would either load json or
+json_pure depending on the system.
+
+So to force using yajl-ruby, you could require 'yajl-ruby' before rest-graph.
+There's no way to force using json when yajl-ruby is already used though.
+Anyone needs this? File a ticket on our [issue tracker][]
+
+[json]: https://github.com/flori/json
+[yajl-ruby]: https://github.com/brianmario/yajl-ruby
+[yajl-ruby's README]: https://github.com/brianmario/yajl-ruby/blob/master/README.rdoc
+[issue tracker]: https://github.com/cardinalblue/rest-graph/issues
+
+## Rack (optional, needed when parsing cookie)
+
+Actually I wonder if anyone would not use [Rack][]. But since it's really
+optional, so I'll just leave it as optional.
+
+## RR (optional, needed when using rest-graph/test_util)
+
+test_util is built on top of [RR][], so to use test_util, RR is required.
+
+[RR]: https://github.com/btakita/rr

data/doc/design.md

@@ -0,0 +1,206 @@
+
+# Design
+
+## Introduction
+
+rest-graph is a lightweight Facebook Graph API client.  By lightweight, it
+means it's modular and compact, and only provides essential functionality.
+It's designed to be transparent to Facebook Graph API, so it doesn't try to
+fix Facebook's bugs nor inconsistency problems.  People should be able to
+read Facebook's documentation (though sometimes it's not quite helpful) in
+order to use rest-graph, instead of learning how rest-graph would work.
+(of course, Ruby experience is required.)
+
+In other words, before starts, you might need to know how Facebook's Graph
+API works, for example, how to fetch data, how to do authentication, etc.
+Here's the links:
+
+* Graph API: <http://developers.facebook.com/docs/reference/api>
+* Authentication: <http://developers.facebook.com/docs/authentication>
+
+For advanced usage, you might want to read the followings, too:
+
+* FQL: <http://developers.facebook.com/docs/reference/fql>
+* Old REST API: <http://developers.facebook.com/docs/reference/rest>
+
+Since rest-graph is trying to be transparent to Facebook Graph API, some
+might find it's not so useful because of Facebook's bugs or inconsistency
+problems.  This might be a disadvantage comparing to others client libraries
+which mimic the issues for you, but the advantage would be for people who
+have already known how Facebook Graph API works, say, people who used to
+develop Facebook Apps with PHP or any other tools, could easily know how to
+use rest-graph with their old knowledges.  On the other hand, if Facebook
+fixed their bugs or inconsistency problems, you don't need to wait for
+rest-graph fixing the problems.  You will directly depend on Facebook,
+but not depend on rest-graph which depends on Facebook.  More layers,
+more problems.  rest-graph is a client library, but not Facebook framework.
+
+Still, if the inconsistency problems are very obvious and would not change
+in the near future, for example, `oauth/access_token` API would not return
+a JSON as typical Graph APIs do, instead, it returns a query string as in
+URL.  In this case, rest-graph uses `Rack::Utils.parse_query` to parse the
+query for you.  If you feel there are more cases rest-graph should handle
+like this, please feel free to file a ticket on our [issue tracker][] on
+Github.
+
+* <https://github.com/cardinalblue/rest-graph/issues>
+
+Or you could start a topic on our mailing list:
+
+* <http://groups.google.com/group/rest-graph/topics>
+
+Either one is welcomed.
+
+## Name
+
+[rest-graph][] is named after its first dependency [rest-client][].
+
+[rest-graph]: https://github.com/cardinalblue/rest-graph
+[rest-client]: https://github.com/archiloque/rest-client
+
+## License
+
+rest-graph is licensed under Apache License 2.0.
+
+## Target Usage
+
+rest-graph is split into many parts to better target different users coming
+from different areas.  Essentially, the core functionality is all in one file
+which is `lib/rest-graph/core.rb`.  You can copy that file and put into your
+projects' load path, or use gem to install rest-graph, and then just require
+the file with `require 'rest-graph/core'`.  If you don't care about memory
+footprint or code bloats, want something that "Just Work&trade;" it's ok to
+just `require 'rest-graph'`.  It would try to load up anything you *might*
+or *might not* need.  It should Just Work&trade; out of the box, otherwise,
+please file a ticket on our [issue tracker][].
+
+[issue tracker]: https://github.com/cardinalblue/rest-graph/issues
+
+Target usages are as following:
+
+* No matter where rest-graph whould be used, for convenience and laziness,
+  just `require 'rest-graph'`.  Then you're good to go.
+
+* Used in backend engine or non-web application.  You might only want the
+  core functionality that rest-graph provides.  In this case, simply use
+  `require 'rest-graph/core'`
+
+* Used in web applications, and then mostly you'll want more than the core.
+  For example, how to get the access token, how to authenticate to Facebook,
+  and how to use different settings (e.g. app_id, secret, etc) in different
+  environments.  In this case, you'll want `require 'rest-graph/rails_util'`
+  (if your web framework is Rails) and `require 'rest-graph/config_util'`.
+  See below for usages of those two extra utilities.
+
+## File Structure
+
+rest-graph is modular, so utilities are all separated.  Different `require`
+will get you different things.  Here we list all different requires.
+
+* `require 'rest-graph'`
+
+  This is for convenience and lazies which just loads everything.
+  You can see below for usages.
+
+* `require 'rest-graph/core'`
+
+  This is for the core functionality.  Other than API calls (which is
+  documented in [rdoc][]), you might want to have some default values
+  for `RestGraph.new`, then you don't have to do this all the time:
+  `RestGraph.new(:app_id => '1829')`.  For example, you might want:
+  `RestGraph.new.app_id` to return value `'1829'` instead of `nil`,
+  and still be able to overwrite it when passing `:app_id` like this:
+  `RestGraph.new(:app_id => 'abcd')`. If so, you'll do:
+
+      require 'rest-graph/core'
+
+      module MyRestGraphSettings
+        def default_app_id
+          '1829'
+        end
+      end
+
+      RestGraph.send(:extend, MyRestGraphSettings)
+
+      RestGraph.new.app_id # => '1829'
+
+  Or you can simply define it in `RestGraph`.
+
+      class RestGraph
+        def self.default_app_id
+          '1829'
+        end
+      end
+
+      RestGraph.new.app_id # => '1829'
+
+  If you want to set those defaults in a config file with different
+  environments, then `require 'rest-graph/config_util'` is for you.
+  See below.
+
+[rdoc]: http://rdoc.info/projects/cardinalblue/rest-graph
+
+* `require 'rest-graph/config_util`
+
+  This is for automatically reading settings from a certain config file.
+  To use it, use: `RestGraph.load_config(path_to_yaml_file, environment)`
+  A config file would look like this: [rest-graph.yaml][]  You can embed
+  ERB template in it.  After the config has been loaded, every call to
+  `RestGraph.new` would respect those settings.  e.g. `RestGraph.new.app_id`
+  would return the app_id you set in the config file, instead of `nil`.
+
+[rest-graph.yaml]: ../test/config/rest-graph.yaml
+
+* `require 'rest-graph/rails_util'`
+
+  This is for people using Rails. (compatible and tested with both Rails 2
+  and Rails 3)  `include RestGraph::RailsUtil` in your controller would
+  give you `rest_graph_setup` and `rest_graph` methods in both controller
+  and helper.  The former is used to configure the behaviour for each action,
+  the latter is used to access the instance of `RestGraph` which is setup in
+  `rest_graph_setup`.
+
+  See [rails.md][] to learn more about this utility.
+
+[rails.md]: rails.md
+
+* `require 'rest-graph/test_util'`
+
+  Quoted from Wikipedia's description about [Unit testing][]:
+
+  > Ideally, each test case is independent from the others: substitutes
+  > like method stubs, mock objects, fakes and test harnesses can be
+  > used to assist testing a module in isolation.
+
+  We won't even want to be depending on the Internet.  It's slow, and
+  unstable.  You might have already tried [webmock][] or [fakeweb][],
+  they are good tools, but a bit tedious to use if we're faking graph
+  API calls.  That's why `RestGraph::TestUtil` comes into play.  It uses
+  [RR][] to make stubs for API calls, and you can change the data that
+  the stubs provide.  This way, it's a lot easier to test your application.
+
+  You can emulate a user login with `RestGraph::TestUtil.login(1234)`,
+  which will give you a fake user data upon calling `/me`.  It will
+  give you a fake access token, too.
+
+  See [test.md][] to learn more about this utility.
+
+  See Martin Fowler's great article to learn more about mocks:
+  [Mocks Aren't Stubs][]
+
+[Unit testing]: http://en.wikipedia.org/wiki/Unit_testing
+[webmock]: https://github.com/bblimke/webmock
+[fakeweb]: https://github.com/chrisk/fakeweb
+[RR]: https://github.com/btakita/rr
+[test.md]: test.md
+[Mocks Aren't Stubs]: http://martinfowler.com/articles/mocksArentStubs.html
+
+* `require 'rest-graph/facebook_util'`
+
+  Facebook has some very inconsistent behaviour.  This utility is here to
+  fix those inconsistencies, providing you a more comprehensive operation
+  on data.  Also, it has permission list build in, without the trouble
+  looking through Facebook's documentation.
+
+  This utility is not fully and carefully written, please file a ticket
+  on our [issue tracker][] if you want something not presented currently.

data/doc/rails.md

@@ -0,0 +1,12 @@
+
+# Rails
+
+## Introduction
+
+## Standalone Website
+
+## Facebook iframe Canvas
+
+## Config
+
+## Options

data/doc/test.md

@@ -0,0 +1,46 @@
+
+# Test
+
+## Introduction
+
+A collection of tools integrated with [RR][] to ease the pain of
+testing. There are 3 levels of tools to stub the result of
+calling APIs. The highest level is `TestUtil.login(1234)` which
+would stub a number of results to pretend the user 1234 is
+logged-in.
+
+The second level are the get/post/put/delete methods for
+TestUtil. For example, to make rg.get('1234') return a
+particular value (such as a hash {'a' => 1}), use
+TestUtil.get('1234'){ {'a' => 1} } to set it up to return
+the specified value (typically a hash).
+
+The third level is for setting default_data and default_response
+for TestUtil. The default_data is the default value for rg.data,
+which includes the access_token and the user_id (uid). The
+default_response is the response given by any RestGraph API call
+(e.g. get, post) when no explicit response has been defined in
+the second level.
+
+To use TestUtil, remember to install RR (gem install rr) and
+require 'rest-graph/test_util'. Then put
+RestGraph::TestUtil.setup before any test case starts, and put
+RestGraph::TestUtil.teardown after any test case ends. Setup
+would stub default_data and default_response for you, and
+teardown would remove any stubs on RestGraph. For Rails, you
+might want to put these in test_helper.rb under "setup" and
+"teardown" block, just as the name suggested. For bacon or
+rspec style testing, these can be placed in the "before" and
+"after" blocks.
+
+In addition, you can get the API calls history via
+RestGraph::TestUtil.history. This would get cleaned up in
+RestGraph::TestUtil.teardown as well.
+
+[RR]: https://github.com/btakita/rr
+
+## Login emulation
+
+## default_response
+
+##

data/doc/tutorial.md

@@ -0,0 +1,142 @@
+The code in this tutorial could be found on [samplergthree][]
+
+[samplergthree]: https://github.com/cardinalblue/samplergthree
+
+# How to build a Facebook application within Rails 3 using the RestGraph gem
+
+1. Before you start, I strongly recommend reading these:
+
+    * Apps on Facebook.com -> <http://developers.facebook.com/docs/guides/canvas/>
+    * Graph API -> <http://developers.facebook.com/docs/reference/api/>
+    * Authentication -> <http://developers.facebook.com/docs/authentication/>
+    * Heroku: Building a Facebook Application -> <http://devcenter.heroku.com/articles/facebook/>
+
+
+2. Go to [FB Developers website](http://facebook.com/developers) and create a new FB app. Set its canvas name, canvas url and your site URL. Make sure the canvas type is set to "iframe" (which should be the case by default).
+
+
+3. Build a new Rails application.
+
+        rails new <name>
+
+
+4. Declare RestGraph and its dependencies in the Gemfile. Add these lines:
+
+        gem 'rest-graph'
+
+        # these gems are used in rest-graph
+        gem 'rest-client', '>=1.6'
+        gem 'json'        # you may also use other JSON parsers/generators, i.e. 'yajl-ruby' or 'json_pure'
+
+
+5. In order to configure your Rails application for the Facebook application you created, you must create a rest-graph.yaml file in your /config directory and fill it with your Facebook configuration. If you plan to run your application in the Facebook canvas, also provide a canvas name.
+
+	Example:
+
+        development:
+            app_id: 'XXXXXXXXXXXXXX'
+            secret: 'YYYYYYYYYYYYYYYYYYYYYYYYYYY'
+            callback_host: 'my.dev.host.com'
+
+        production:
+            app_id: 'XXXXXXXXXXXXXX'
+            secret: 'YYYYYYYYYYYYYYYYYYYYYYYYYYY'
+            canvas: 'yourcanvasname'
+            callback_host: 'my.production.host.com'
+
+
+    If you push to Heroku, your production callback_host should be `yourappname.heroku.com`. You can also access your app directly running `rails server` (or just `rails s`) in your console, but if you do not have an external IP address (e.g. you are behind a NAT), you will need to use a service called a tunnel in order to make your application accessible to the outer world (and Facebook callbacks). You'll find more information on setting up a tunnel here: <http://tunnlr.com/>.
+
+6. Let's create a first controller for your app - ScratchController.
+
+        rails generate controller Scratch
+
+7. The next step will be to include rest-graph in your controller. You should put this line in:
+
+        include RestGraph::RailsUtil
+
+     Now you can make use of the RestGraph commands :)
+
+8. To actually use rest-graph in a controller action, you will need to first call "rest_graph_setup", which reads the configuration from the rest-graph.yaml and creates a rest_graph object.   Let's set this up in a before_filter.
+
+    Add this line after the `include RestGraph::RailsUtil`:
+
+        before_filter :filter_setup_rest_graph
+
+    And declare filter_setup_rest_graph as a private function:
+
+        private
+
+        def filter_setup_rest_graph
+            rest_graph_setup(:auto_authorize => true)
+        end
+
+    The `:auto_authorize` argument of rest_graph_setup tells RestGraph to redirect users to the app authorization page if the app is not authorized yet.
+
+    Hooray! You can now perform all kinds of Graph API operations using the rest_graph object.
+
+9. Let's start with following sample action in the Scratch controller:
+
+        def me
+            render :text => rest_graph.get('me').inspect
+        end
+
+10. To run this, go to the /config/routes.rb file to set up the default routing. For now you will just need this line:
+
+        match ':controller/:action'
+
+11. Commit your change in git, and then push to Heroku:
+
+        git add .
+        git commit -m "first test of rest-graph using scratch/me"
+        git push heroku master
+
+    After you push your app to Heroku, you can open <http://yourappname.heroku.com/scratch/me> in your browser. If you are not yet logged into Facebook, it will ask you to log in.  If you are logged in your Facebook account, this address should redirect you to the authorization page and ask if you want to let your application access your public information. After you confirm, you should be redirected back to 'scratch/me' action which will show your basic information.
+
+12. To see other information, such as your home feed, is very easy. You can add another sample action to your controller:
+
+        def feed
+            render :text => rest_graph.get('me/home').inspect
+        end
+
+    If you will push the changes to Heroku and go to <http://yourappname.heroku.com/scratch/feed>, the page should display a JSON hash with all the data from your Facebook home feed.
+
+
+13. Now let's try to access your Facebook wall. You need to add a new action to your controller:
+
+        def wall
+            render :text => rest_graph.get('me/feed').inspect
+        end
+
+    Note that Facebook's naming is such that your home news feeds is accessed via `me/home` and your profile walls is accessed via `me/feed` ...
+
+    Actually, I need to warn you that this time the action won't work properly. Why? Because users didn't grant you the permission to access their walls! You need to ask them for this special permission and that means you need to add something more to your controller.
+
+    So, we will organize all the permissions we need as a scope and pass them to the rest_graph_setup call. I find it handy to make the scope array and declare what kind of permissions I need just inside this array. If you feel it's a good idea, you can add this line to your private setup function, just before you call rest_graph_setup:
+
+        scope = []
+        scope << 'read_stream'
+
+    The only permission you need right now is the 'read_stream' permission. You can find out more about different kinds of user permissions here: <http://developers.facebook.com/docs/authentication/permissions/>
+
+    You also need to add the auto_authorize_scope argument to the rest_graph_setup. It will look this way now:
+
+        rest_graph_setup(:auto_authorize => true, :auto_authorize_scope => scope.join(','))
+
+    As you see, you might as well pass the argument like this `:auto_authorize_scope => 'read_stream'`, but once you have to get a lot of different permissions, it's very useful to put them all in an array, because it's more readable and you can easily delete or comment out any one of them.
+
+    Now save your work and push it to Heroku or just try in your tunneled development environment. /scratch/wall URL should give you the hash with user's wall data now!
+
+    Remember. Anytime you need to get data of a new kind, you need to ask user for a certain permission first and that means you need to declare this permission in your scope array!
+
+14. What else? If you know how to deal with hashes then you will definitely know how to get any kind of data you want using the rest_graph object. Let's say you want to get a last object from a user's wall (last in terms of time, last posted, so the first on the wall and therefore first to Ruby). Let's take a look at the /scratch/feed page. The hash which is printed on this page has 2 keys - data and paging. Let's leave the paging key aside. What's more interesting here comes as a value of 'data'. So the last object in any user's wall will be simply:
+
+        rest_graph.get('me/feed')['data'].first
+
+    Now let's say you want only to keep the name of the author of this particular object. You can get it by using:
+
+        rest_graph.get('me/feed')['data'].first['from']['name']
+
+    That's it!
+
+15. More information on customizing RestGraph and its functions are to be found here: <https://github.com/cardinalblue/rest-graph>