Disqus API for Ruby

Provides clean Disqus REST API for your Ruby app. Currently supported API version: 3.0.

Rails >3.0 is also supported.

Install

gem install disqus_api

Configure

If you are not using Rails:

require 'disqus_api'

DisqusApi.config = {api_secret: 'secret key',
                    api_key: 'public key',
                    access_token: 'token from app settings'}

For Rails users:

Put in your config/disqus_api.yml:

development:
  api_secret: development_secret_key
  api_key: 'public key'
  access_token: 'token from app settings'

production:
  api_secret: production_secret_key
  api_key: 'public key'
  access_token: 'token from app settings'

# ... any other env

Enjoy

DisqusApi.v3.users.details
# => {"code" => 0, "response" => {
#                     "isFollowing"=>false,
#                     "isFollowedBy"=>false, "connections"=>{}, "isPrimary"=>true, "id"=>"84792962"
#                     ...
#                  }

Use response to get response body

DisqusApi.v3.users.details.response
# => {
#       "isFollowing"=>false,
#       "isFollowedBy"=>false, "connections"=>{}, "isPrimary"=>true, "id"=>"84792962"
#       ...
#    }

Alias #body for response body

DisqusApi.v3.users.details.body
# => {
#       "isFollowing"=>false,
#       "isFollowedBy"=>false, "connections"=>{}, "isPrimary"=>true, "id"=>"84792962"
#       # ...
#    }

Setting additional parameters to a query

DisqusApi.v3.posts.list(forum: 'my_form')

Fetching full collections

By default Disqus API limits returning collections by 25 records per requests. The maximum limit you can set is 100. In order to fetch all records from a collection use #all method:

DisqusApi.v3.posts.list(forum: 'my_form').all

Pagination

Step by step:

first_page  = DisqusApi.v3.posts.list(forum: 'my_forum', limit: 10)

second_page = first_page.next
third_page  = second_page.next
first_page  = third_page.prev.prev
# ...

It is useful to go through all records. This way you will pass every page in batches by 10:

DisqusApi.v3.posts.list(limit: 10).each_resource do |comment|
  puts comment.inspect
end

You can also iterate collection page by page.

DisqusApi.v3.posts.each_page do |comments|
  comments.each do |comment|
    puts comment.inspect
  end
end

You can also move on next page:

response = DisqusApi.v3.posts
response.next!

Or on previous one:

response.prev!

Performing custom requests

DisqusApi.v3.get('posts/list.json', forum: 'my_forum')
DisqusApi.v3.post('posts/create.json', forum: 'my_forum')

Handling exceptions

Just catch DisqusApi::InvalidApiRequestError. It has code to identify problems with a request.

begin
  DisqusApi.v3.posts.list(forum: 'something-wrong')
rescue DisqusApi::InvalidApiRequestError => e
  e.response.inspect
end

#=> {"code"=>2, "response"=>"Invalid argument, 'forum': Unable to find forum 'something-wrong'"}

Using in test environment

before :all do
  # You can move this block in RSpec initializer or `spec_helper.rb`

  DisqusApi.stub_requests do |stub|
    stub.get('/api/3.0/users/details.json') { [200, {}, {code: 0, body: {response: :whatever}}.to_json] }
  end
end

it 'performs requests' do
  DisqusApi.v3.users.details['code'].should == 0
end

Disqus API uses Faraday gem, refer to its documentation for details.

Running specs

Use any of the following commands from the project directory:

rspec
rake # rake gem must be installed

In order to test on a real Disqus account - specify spec/config/disqus.yml (see spec/config/disqus.yml.example for details) - run specs passing USE_DISQUS_ACCOUNT environment variable:

USE_DISQUS_ACCOUNT=1 rspec

Contributing to disqus_api


This project is licensed under the terms of the MIT license.