Class: Akismet::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/akismet/client.rb

Overview

A Ruby client for the Akismet API.

Examples:


# Verify an API key
#

Akismet::Client.new( 'apikey123', 'http://jonahb.com' ).verify_key

# Check whether a comment is spam
#

client = Akismet::Client.new( 'apikey123',
  'http://jonahb.com',
  :app_name => 'jonahb.com',
  :app_version => '1.0' )

# assumes variables comment, post_url, request (a racklike HTTP request)
spam = client.comment_check( request.remote_ip,
  request.user_agent,
  :content_type => 'comment',
  :referrer => request.headers[ 'HTTP_REFERER' ],
  :permalink => post_url, 
  :comment_author => comment.author,
  :comment_author_email => comment.author_email,
  :comment_content => comment.body )

if spam
  # ...
end 

# Submit a batch of checks using a single TCP connection
#

client = Akismet::Client.new( 'apikey123',
  'http://jonahb.com',
  :app_name => 'jonahb.com',
  :app_version => '1.0' )

begin
  client.open
  comments.each do |comment|
    client.comment_check( ... )  # see example above
  end
ensure
  client.close
end

# ... or ...

Akismet::Client.open( 'apikey123',
  'http://jonahb.com',
  :app_name => 'jonahb.com',
  :app_version => '1.0' ) do |client|
  comments.each do |comment|
    client.comment_check( ... )  # see example above
  end
end

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key, home_url, options = {}) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String) —

    The API key obtained at akismet.com.

  • home_url (String) —

    The URL of the home page of the application making the request.

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :app_name (String) —

    The name of the application making the request, e.g. “jonahb.com”. Forms part of the User-Agent header submitted to Akismet.

  • :app_version (String) —

    The version of the application making the request, e.g. “1.0”. Forms part of the User-Agent header submitted to Akismet. Ignored if :app_name is not privded.



109
110
111
112
113
114
 
# File 'lib/akismet/client.rb', line 109

def initialize( api_key, home_url, options = {} )
  @api_key = api_key
  @home_url = home_url
  @app_name = options[ :app_name ]
  @app_version = options[ :app_version ]
end

Instance Attribute Details

#api_key ⇒ String (readonly)

The API key obtained at akismet.com.

Returns:

  • (String) 


76
77
78
 
# File 'lib/akismet/client.rb', line 76

def api_key
  @api_key
end

#app_name ⇒ String (readonly)

The name of the application making the request, e.g “jonahb.com”.

Returns:

  • (String) 


88
89
90
 
# File 'lib/akismet/client.rb', line 88

def app_name
  @app_name
end

#app_version ⇒ String (readonly)

The version of the application making the request, e.g. “1.0”.

Returns:

  • (String) 


94
95
96
 
# File 'lib/akismet/client.rb', line 94

def app_version
  @app_version
end

#home_url ⇒ String (readonly)

The URL of the home page of the application making the request.

Returns:

  • (String) 


82
83
84
 
# File 'lib/akismet/client.rb', line 82

def home_url
  @home_url
end

Class Method Details

.open(api_key, home_url, options = {}) {|Akismet::Client| ... } ⇒ nil

Yields a new open Client, closing the Client when the block returns. Takes the same arguments as #initialize. Use for submitting a batch of requests using a single TCP and HTTP session.

Yields:

Returns:

  • (nil)

See Also:



126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/akismet/client.rb', line 126

def self.open( api_key, home_url, options = {} )
  raise "Block required" unless block_given?
  client = nil
  begin
    client = new( api_key, home_url, options )
    client.open
    yield client
  ensure
    client.close if client
  end
  nil
end

Instance Method Details

#close ⇒ self

Closes the Client.

Returns:

  • (self)

See Also:



169
170
171
172
173
 
# File 'lib/akismet/client.rb', line 169

def close
  @http_session.finish if open?
  @http_session = nil
  self
end

#comment_check(user_ip, user_agent, params = {}) ⇒ boolean

Checks whether a comment is spam. You are encouraged the submit, in addition to the documented parameters, data about the client and the comment submission. For example, if the client is an HTTP server, include HTTP headers and environment variables.

If the Client is not open, opens it for the duration of the call.

Parameters:

  • user_ip (String) —

    The IP address of the submitter of the comment.

  • user_agent (String) —

    The user agent of the web browser submitting the comment. Typically the HTTP_USER_AGENT CGI variable. Not to be confused with the user agent of the Akismet library.

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :referrer (String) —

    The value of the HTTP_REFERER header. Note that the parameter is spelled with two consecutive ‘r’s.

  • :permalink (String) —

    The permanent URL of the entry to which the comment pertains.

  • :comment_type (String) —

    ‘comment’, ‘trackback’, ‘pingback’, or a made-up value like ‘registration’

  • :comment_author (String) —

    The name of the author of the comment.

  • :comment_author_email (String) —

    The email address of the author of the comment.

  • :comment_author_url (String) —

    A URL submitted with the comment.

  • :comment_content (String) —

    The text of the comment.

Returns:

  • (boolean)

Raises:



232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/akismet/client.rb', line 232

def comment_check( user_ip, user_agent, params = {} )
  response = invoke_comment_method( 'comment-check',
    user_ip,
    user_agent,
    params )

  unless %w{ true false }.include?( response.body )
    raise_with_response response
  end

  response.body == 'true'
end

#open ⇒ self

Opens the client. You may use this method in combination with #close to submit a batch of requests using a single TCP and HTTP session.

If you don’t call this before calling #comment_check, #submit_ham, or #submit_spam, a session will be created and opened for the duration of the call.

Note that calls to #verify_key always create a session. This is due to a peculiarity of the Akismet API where #verify_key requests must be sent to a different host.

Returns:

  • (self)

Raises:

  • (RuntimeError) —

    The client is already open.

See Also:



157
158
159
160
161
162
 
# File 'lib/akismet/client.rb', line 157

def open
  raise "Already open" if open?
  @http_session = Net::HTTP.new( "#{ api_key }.rest.akismet.com", 80 )
  @http_session.start
  self
end

#open? ⇒ boolean

Whether the Client is open.

Returns:

  • (boolean) 


179
180
181
 
# File 'lib/akismet/client.rb', line 179

def open?
  @http_session && @http_session.started?
end

#submit_ham(user_ip, user_agent, params = {}) ⇒ nil

Submits a comment that has been identified as not-spam (ham). Takes the same arguments as #comment_check. If the Client is not open, opens it for the duration of the call.

Returns:

  • (nil)

Raises:

See Also:



254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/akismet/client.rb', line 254

def submit_ham( user_ip, user_agent, params = {} )
  response = invoke_comment_method( 'submit-ham',
    user_ip,
    user_agent,
    params )

  unless response.body == 'Thanks for making the web a better place.'
    raise_from_response response
  end

  nil
end

#submit_spam(user_ip, user_agent, params = {}) ⇒ nil

Submits a comment that has been identified as spam. Takes the same arguments as #comment_check. If the Client is not open, opens it for the duration of the call.

Returns:

  • (nil)

Raises:

See Also:



276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/akismet/client.rb', line 276

def submit_spam( user_ip, user_agent, params = {} )
  response = invoke_comment_method( 'submit-spam',
    user_ip,
    user_agent,
    params )

  unless response.body == 'Thanks for making the web a better place.'
    raise_from_response response
  end

  nil
end

#verify_key ⇒ boolean

Checks the validity of the API key.

Returns:

  • (boolean) 


187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/akismet/client.rb', line 187

def verify_key
  response = Net::HTTP.start( 'rest.akismet.com', 80 ) do |session|
    invoke( session, 'verify-key', :blog => home_url, :key => api_key )
  end

  unless %w{ valid invalid }.include?( response.body )
    raise_with_response response
  end

  response.body == 'valid'
end