Merge pull request #90 from pusher/jf-pusher-api-methods

Add docs on #channel_info and #channels

Author: jackfranklin

README.md

@@ -125,21 +125,17 @@ Pusher['a_channel'].trigger('an_event', {:some => 'data'})
 
 This will continue to work, but has been replaced by `Pusher.trigger` which supports one or multiple channels.
 
-### Generic requests to the Pusher REST API
+### Using the Pusher REST API
 
-Aside from triggering events, the REST API also supports a number of operations for querying the state of the system. A reference of the available methods is available at <http://pusher.com/docs/rest_api>.
+This gem provides methods for accessing information from the [Pusher REST API](https://pusher.com/docs/rest_api). The documentation also shows an example of the responses from each of the API endpionts.
 
-All requests must be signed by using your secret key, which is handled automatically using these methods:
+The following methods are provided by the gem.
 
-``` ruby
-# using the Pusher class
-Pusher.get('url_without_app_id', params)
+- `Pusher.channel_info('channel_name')` returns information about that channel.
 
-# using a client
-pusher_client.post('url_without_app_id', params)
-```
+- `Pusher.channel_users('channel_name')` returns a list of all the users subscribed to the channel.
 
-Note that you don't need to specify your app_id in the URL, as this is inferred from your credentials.
+- `Pusher.channels` returns information about all the channels in your Pusher application.
 
 ### Asynchronous requests
 

lib/pusher.rb

@@ -31,7 +31,7 @@ class << self
     def_delegators :default_client, :timeout=, :connect_timeout=, :send_timeout=, :receive_timeout=, :keep_alive_timeout=
 
     def_delegators :default_client, :get, :get_async, :post, :post_async
-    def_delegators :default_client, :channels, :channel_info, :trigger, :trigger_async
+    def_delegators :default_client, :channels, :channel_info, :channel_users, :trigger, :trigger_async
     def_delegators :default_client, :authenticate, :webhook, :channel, :[]
 
     attr_writer :logger

lib/pusher/client.rb

@@ -209,6 +209,22 @@ def channel_info(channel_name, params = {})
       get("/channels/#{channel_name}", params)
     end
 
+    # Request info for users of a channel
+    #
+    # GET /apps/[id]/channels/[channel_name]/users
+    #
+    # @param channel_name [String] Channel name (max 200 characters)
+    # @param params [Hash] Hash of parameters for the API - see REST API docs
+    #
+    # @return [Hash] See Pusher API docs
+    #
+    # @raise [Pusher::Error] Unsuccessful response - see the error message
+    # @raise [Pusher::HTTPError] Error raised inside http client. The original error is wrapped in error.original_error
+    #
+    def channel_users(channel_name, params = {})
+      get("/channels/#{channel_name}/users", params)
+    end
+
     # Trigger an event on one or more channels
     #
     # POST /apps/[app_id]/events

spec/client_spec.rb

@@ -128,6 +128,21 @@
         end
       end
 
+      describe '#channel_users' do
+        it "should call correct URL and symbolise response" do
+          api_path = %r{/apps/20/channels/mychannel/users}
+          stub_request(:get, api_path).to_return({
+            :status => 200,
+            :body => MultiJson.encode({
+              'users' => [{ 'id' => 1 }]
+            })
+          })
+          expect(@client.channel_users('mychannel')).to eq({
+            :users => [{ 'id' => 1}]
+          })
+        end
+      end
+
       describe '#authenticate' do
         before :each do
           @custom_data = {:uid => 123, :info => {:name => 'Foo'}}