Class: Disqus::Api

Inherits:
Object
  • Object
show all
Defined in:
lib/disqus/api.rb

Overview

Disqus API

The Api class implements the Disqus API directly. It is not really intended to be used directly, but rather to use the domain objects of Forum, Thread, Post, Author and AnonymousAuthor. For full information on the Disqus API, please see the Disqus developer info.

Each method in the Api class takes as a single argument a hash of options, and returns a Hash with 3 keys:

  • ‘succeeded’ - contains true or false indicating whether the API call succeeded

  • ‘code’ - if the API call did not succeed, this will contain an error code.

  • ‘message’ - contains the object being returned on success, or an error message on failure.

API Keys

There are two different kinds of API keys:

User Keys

Every Disqus account has a User Key; it is used to perform actions associated with that account. This can be passed in as an option, or configured as follows:

Disqus::defaults[:api_key] = "the_user_api_key"

Forum Keys

Every Disqus forum has a Forum Key. It can be shared among trusted moderators of a forum, and is used to perform actions associated with that forum. The creator of a forum can get the forum’s key through the API.

Constant Summary collapse

ROOT = 
'http://disqus.com/api'
API_VERSION = 
'1.1'

Class Method Summary collapse

Class Method Details

.comment_form(forum_shortname, thread_identifier) ⇒ Object

Widget to includes a comment form suitable for use with the Disqus API. This is different from the other widgets in that you can specify the thread identifier being commented on.



215
216
217
218
219
220
221
222
223
 
# File 'lib/disqus/api.rb', line 215

def comment_form(forum_shortname, thread_identifier)
  url = 'http://disqus.com/api/reply.js?' + 
    "forum_shortname=#{escape(forum_shortname)}&" + 
    "thread_identifier=#{escape(thread_identifier)}"
  s = '<div id="dsq-reply">'
  s << '<script type="text/javascript" src="%s"></script>' % url
  s << '</div>'
  return s
end

.create_post(opts = {}) ⇒ Object

Creates a new post on the thread. Does not check against spam filters or ban list. This is intended to allow automated importing of comments.

Returns a Hash containing a representation of the post just created:

Required options hash elements:

  • :forum_api_key - the API key for the forum

  • :thread_id - the thread to post to

  • :message - the content of the post

  • :author_name - the post creator’s name

  • :author_email - the post creator’s email address

Optional:

  • :parent_post - the id of the parent post

  • :created_at - the UTC date this post was created, in the format %Y-%m-%dT%H:%M (the current time will be used by default)

  • :author_url - the author’s homepage

  • :ip_address - the author’s IP address



65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/disqus/api.rb', line 65

def create_post(opts = {})
  opts[:api_key] ||= Disqus::defaults[:api_key]
  post_data = {
    :forum_api_key => opts[:forum_api_key],
    :thread_id     => opts[:thread_id],
    :message       => opts[:message],
    :author_name   => opts[:author_name],
    :author_email  => opts[:author_email]
  }
  [:parent_post, :created_at, :author_url, :ip_address].each do |key|
    post_data[key] = opts[key] if opts[key]
  end
  JSON.parse(post('create_post/', post_data))
end

.get_forum_api_key(opts = {}) ⇒ Object

Returns A string which is the Forum Key for the given forum.

Required options hash elements:

  • :forum_id - the unique id of the forum

Optional:



101
102
103
104
 
# File 'lib/disqus/api.rb', line 101

def get_forum_api_key(opts = {})
  opts[:api_key] ||= Disqus::defaults[:api_key]
  JSON.parse(get('get_forum_api_key', :user_api_key => opts[:api_key], :forum_id => opts[:forum_id]))
end

.get_forum_list(opts = {}) ⇒ Object

Returns an array of hashes representing all forums the user owns. The user is determined by the API key.

Options:



87
88
89
90
 
# File 'lib/disqus/api.rb', line 87

def get_forum_list(opts = {})
  opts[:api_key] ||= Disqus::defaults[:api_key]
  JSON.parse(get('get_forum_list', :user_api_key => opts[:api_key]))
end

.get_num_posts(opts = {}) ⇒ Object

Returns a hash having thread_ids as keys and 2-element arrays as values.

The first array element is the number of visible comments on on the thread; this would be useful for showing users of the site (e.g., “5 Comments”).

The second array element is the total number of comments on the thread.

These numbers are different because some forums require moderator approval, some messages are flagged as spam, etc.

Required options hash elements:

  • :forum_api_key - the API key for the forum

  • :thread_ids - an array of thread IDs belonging to the given forum.



134
135
136
137
 
# File 'lib/disqus/api.rb', line 134

def get_num_posts(opts = {})
  opts[:api_key] ||= Disqus::defaults[:api_key]
  JSON.parse(get('get_num_posts', :thread_ids => opts[:thread_ids].join(","), :forum_api_key => opts[:forum_api_key]))
end

.get_thread_by_url(opts = {}) ⇒ Object

Returns a hash representing a thread if one was found, otherwise null.

It only finds threads associated with the given forum.

Note that there is no one-to-one mapping between threads and URL’s; a thread will only have an associated URL if it was automatically created by Disqus javascript embedded on that page. Therefore, we recommend using thread_by_identifier whenever possible. This method is provided mainly for handling comments from before your forum was using the API.

Required options hash elements:

  • :forum_api_key - the API key for the forum

  • :url - the URL to check for an associated thread



154
155
156
 
# File 'lib/disqus/api.rb', line 154

def get_thread_by_url(opts = {})
  JSON.parse(get('get_thread_by_url', :url => opts[:url], :forum_api_key => opts[:forum_api_key]))
end

.get_thread_list(opts = {}) ⇒ Object

Returns: An array of hashes representing all threads belonging to the given forum.

Required options hash elements:

  • :forum_api_key - the API key for the forum

  • :forum_id - the unique id of the forum



113
114
115
 
# File 'lib/disqus/api.rb', line 113

def get_thread_list(opts = {})
  JSON.parse(get('get_thread_list', :forum_id => opts[:forum_id], :forum_api_key => opts[:forum_api_key]))
end

.get_thread_posts(opts = {}) ⇒ Object

Returns an array of hashes representing representing all posts belonging to the given forum.

Required options hash elements:

  • :forum_api_key - the API key for the forum

  • :thread_id - the ID of a thread belonging to the given forum



165
166
167
 
# File 'lib/disqus/api.rb', line 165

def get_thread_posts(opts = {})
  JSON.parse(get('get_thread_posts', :thread_id => opts[:thread_id], :forum_api_key => opts[:forum_api_key]))
end

.thread_by_identifier(opts = {}) ⇒ Object

Create or retrieve a thread by an arbitrary identifying string of your choice. For example, you could use your local database’s ID for the thread. This method allows you to decouple thread identifiers from the URL’s on which they might be appear. (Disqus would normally use a thread’s URL to identify it, which is problematic when URL’s do not uniquely identify a resource.) If no thread exists for the given identifier yet (paired with the forum), one will be created.

Returns a hash with two keys:

  • “thread”, which is a hash representing the thread corresponding to the identifier; and

  • “created”, which indicates whether the thread was created as a result of this method call. If created, it will have the specified title.

Required options hash elements:

  • :forum_api_key - the API key for the forum

  • :title - the title of the thread to possibly be created

  • :identifier - a string of your choosing



187
188
189
190
191
 
# File 'lib/disqus/api.rb', line 187

def thread_by_identifier(opts = {})
  JSON.parse(post('thread_by_identifier/', :forum_api_key => opts[:forum_api_key],
                                          :identifier => opts[:identifier],
                                          :title => opts[:title] ))
end

.update_thread(opts = {}) ⇒ Object

Sets the provided values on the thread object.

Returns an empty success message.

Required options hash elements:

  • :forum_api_key - the API key for the forum

  • :thread_id - the ID of a thread belonging to the given forum

Optional:

  • :title - the title of the thread

  • :slug - the per-forum-unique string used for identifying this thread in disqus.com URL’s relating to this thread. Composed of underscore-separated alphanumeric strings.

  • :url - the URL this thread is on, if known.

  • :allow_comment - whether this thread is open to new comments



208
209
210
 
# File 'lib/disqus/api.rb', line 208

def update_thread(opts = {})
  JSON.parse(post('update_thread/', opts))
end