Ruby Library

For you Ruby programmers, we've release a RubyGem that will let you quickly and easily access and extract data from the Get Satisfaction API. It is inspired by ActiveResource.

First, an example

The interesting piece is that only made one HTTP call.

Installing the RubyGem

sudo gem install ruby-satisfaction

Getting the Source Code

Using the Library

The first step to using the Ruby library is always to create a Satisfaction object. This object is the root through which you will access all the other pieces of the API, and contains the configuration and cache information.

The Satisfaction object provides access to several Resource Collections through which you get at the data in the system. These root level collections are: companies, people, topics, replies, tags and products.

These Resource Collections are acted upon by two fundamental methods: get and page. get is used to retrieve a singular item while page conversely retrieves a single page of items:

As you can see, get returns a single Resource object and page returns an array of Resource objects.

Note: You cannot access the entirety of a collection of resources directly, you must always do so through a page of resources.

Resource Collections

As mentioned above, the data inside the Satisfaction API is exposed through a set of Resource Collections. Besides the root level collections, each resource has sub-collections of it's own:

  • Companies have: people, employees, topics, products, and tags
  • People have: topics, replies, and followed_topics
  • Topics have: replies, people, products, and tags
  • Tags have: topics, products, and companies
  • Products have: topics, companies, and tags

As you can see, there are many different ways in which you can access the data that is important to your application.

Resources

Resource objects provide access to the detailed information of each piece of data exposed through the API. Need to get the text for a reply? You do so by accessing the reply's resource object. Each type of resource exposes different attributes, and you access these as you would access an attribute of an ActiveRecord model object: 

sfn.people.get("scott").tagline # => "You are free... to do as I tell you."

In this example, tagline is the attribute being accessed.

Lazy Loading

Resources are lazily loaded by default. Calls are only made against the API when necessary. The first time an attribute of a resource is accessed, it will load from the API, for example:

As an alternative, you can explicitly call load on a Resource to pull its attributes from the API.

Authentication

The rubygem exposes to forms of authentication that your application can use: Basic authentication and OAuth. To use basic auth you call set_basic_auth like so: 

sfn.set_basic_auth("scott@getsatisfaction.com", "mypasswordhere")

OAuth uses a token system to authenticate access to the API. Once an access token has been obtained you can use it like so:

Note: Please see our guide to using OAuth to learn about getting an access token.

Posting Topics

Posting topics to Get Satisfaction through the API is fairly simple. After setting your authentication info, simply make a call like so: 

sfn.topics.post(:subject => 'The best topic ever?', :style => 'question')