Ruby, meet Stack Exchange.

Installation is easy, provided you already have Ruby installed. If not, you're probably in the wrong place.

gem install serel

Configuration

To start, drop Serel into your Ruby file of choice, and configure it with your API key and the site you are looking to query.

require 'serel'
Serel::Base.config(:stackoverflow, 'api_key')

I can has API Key?

Don't have an API key? Sign up for one on Stack Apps

Stop logging things

By defaut, Serel will log the URL of every HTTP request made to STDOUT. If you don't want this, you can set the level of the logger to be higher: Serel::Base.logger.level = Logger::WARN

Tour

We'll now go on a whirlwind tour of the basics of Serel. Open up irb and configure Serel as above.

Stack Exchange is all about the questions, right? Lets start there. We'll retrieve a list of the 3 highest voted questions of all time on Stack Overflow, get the first one, find it's owner, and get a relation object with the tags he is active in sorted by name. Completely pointles in a practical sense? Yes, but you'll learn something.

See the little help box to the right for more information on the Relation object.

questions = Serel::Question.pagesize(3).sort('votes').get
=> [#<Serel::Question:70103133675940 @question_id=194812, @answer_count=112, ...>]
question = questions.first
 => #<Serel::Question:70103133675940 @question_id=194812, @answer_count=112, ...>
user = question.owner
 => #<Serel::User:70103133674960 @user_id=11110, @user_type=registered, ...>
relation = user.tags.sort('name')
=> #<Serel::Relation:0x007f8450c09f28 @type="tag", @klass=Serel::Tag, @scope={:api_key=>"0p65aJUHxHo0G19*YF272A((", :site=>:stackoverflow, :url=>"users/11110/tags", :sort=>"name"}, @qty=:plural> 

Here, take this with you

Despite using a library, the Stack Exchange API documentation will be invaluable. It provides all sorts of useful information, particularly with regards to what values are acceptable for which parameters, since this will change across methods.

Ooh, what's this relation object here?

The Serel::Relation class stores information about the current scope of the request. It's what we use to create the awesome chainable interface. You can pass these around if you like, and have reason to. Most people won't deal with Relation objects, but they're frequently used within the library.

Working with access tokens

We have a handy helper class to get from access tokens to a user or to their inbox.

token = Serel::AccessToken.new('token')
=> <Serel::AccessToken @token='token'>
user = token.user
=> <Serel::User>
inbox = token.inbox.get
==> [<Serel::Inbox>,...]

Once you have retrieved the user associated with the access token it's simple to access any of the instance methods on the user - see the User documentation for more information

Most methods return an instance of Serel::Response. This is a thin wrapper around the Array class that allows easy access to the additional attributes in the common wrapper.

> answers = Serel::Answer.get
[INFO][2012-03-31 10:44:35] Making request to /2.0/answers?site=stackoverflow&key=0p65aJUHxHo0G19%2AYF272A%28%28
=> [#<Serel::Answer:70199501159940...>]
> answers.backoff
=> nil
> answers.has_more
=> true
> answers.quota_remaining
=> 99997

The methods used to access the information in the response wrapper are named exactly the same as the fields in the wrapper object.

Some methods don't return a Serel::Response, instead returning a singular class. This is only done where it is obvious that singular responses will be recieved, e.g Answer#question and Info.get_info. The RDocs should indicate which object a method returns.

A complete list of all the API routes, mapped to their Serel equivalent. Note that we also have some additional methods, discussed below the table.

Per site methods

1.0.0

• Change the behaviour of #get to only change the URL scope if the URL is not already set
• Fixed issue with filters that don't return any values
• Improved handling of filters and responses requiring time values

1.0.0.rc1/2

• Released Serel