Ruby PostRank

A simple wrapper around the PostRank.com REST API. I’ve tried to keep the API simple without it being a bare API wrapper.

Walkthrough

I’ve tried to keep the API as simple as possible. It’s about one step above the bare PostRank API. Hopefully the added abstraction is useful. The easiest way to explain this is probably to show an example. So, here we go.

  #!/usr/bin/env ruby

  require 'rubygems'
  require 'postrank'

  include PostRank

  server = Server.new("com.everburning")
  eb = server.feed("http://everburning.com")

  puts "The GREAT everburning feeds"
  eb.entries(:level => Level::GREAT).each do |entry|
    puts entry
  end

  puts "\nThe top 5 posts in the last week on everburning"
  eb.top_posts(:period => Period::WEEK).each do |entry|
    puts "#{entry.title} -- #{entry.post_rank} -- #{entry.post_rank_color}"
  end

  puts "\nGet thematic PostRanked items"
  server.post_rank(["http://flickr.com/photos/14009462@N00/2654539960/",
                    "http://www.flickr.com/photos/21418584@N07/2447928272/",
                    "http://www.flickr.com/photos/pilou/2655293624/"]).each do |entry|
    puts entry
  end

  puts "\nGet PostRanked items"
  server.post_rank(['http://everburning.com/news/on-recent-media/',
                    'http://everburning.com/news/californication/',
                    'http://everburning.com/news/the-weary-traveler/'],
              :feeds => [eb]).each do |entry|
    puts entry
  end

Nothing too special there. Let’s see how this thing works. One thing you may have noticed, some parameters are named, others aren’t. What’s the deal? Well, any required parameter is un-named. It has to be entered so I’m trying to keep the redundancy down. Optional parameters are named. This way to don’t have to enter the three default values just to update a forth parameter. I think this gives the best of both worlds for berivity, clarity and lazyness.

Everything in the PostRank plugin is defined within the PostRank module. So, I’m including PostRank to make my life simpler.

First up, we need to create a server object to handle connecting to the PostRank servers. The Server creation has one required parameter the ‘application key’. This can be set to anything, AideRSS recommends setting it to your domain name. Just something they can identify traffic sources through.

The Server.new(app_key, server, port) call accepts two more parameters which you probably won’t need to use for a while but, you can change the server and port used to connect to the PostRank servers.

Ok, with our server object created the next step is to grab a feed. This is done by calling the Server#feed method. #feed has one required parameter the URL of the feed to be retrieved. You can pass an optional second parameter to feed to specify the feed load priority. The priority is a number between 70 and 100 with 70 as high priority.

A feed has a few pieces of information attached too it. You can retrieve the Feed#feed_id, Feed#url, Feed#link and Feed#title. Note, the title is only set after entries have been retrieved. If no entries have been queried the title will be the url.

With our feed in hand we can grab some feed information. We do this through the Feed#entries call. Feed#entries accepts three optional parameters. The level of items (Level::GREAT, Level::ALL, Level::GOOD, etc), the number of items to retrieve from the servers (between 1 and 30) and the start index to retrieve from (for pagination purposes). We just use the default Entry#to_s method to print out the url and the post rank of the entries.

Instead of querying the whole feed we can query specifically for the top posts in the feed. This is done using the Feed#top_posts method. top_posts accepts two optional parameters. The first is the time period to query within (Period::DAY, Period::WEEK, Period::MONTH, etc) and the second is the count of items to return (1 to 30).

The final method we use is the Server#post_rank method. This will return post rank information for the URLs provided. The URL parameter is required when querying Server#post_rank. The feeds parameter is optional. Each parameter accepts an array. The URL array is the set of URLs in String format that you want to lookup. The feeds array is an array of Feed objects.

That’s basically it.

Contact

If you’ve got any questions, comments or bugs, please let me know. You can contact me by email at dj2 at everburning dot com.