Developer Documentation

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

        require 'satisfaction'  
          
        sfn = Satisfaction.new  
        #let's find the subject of my latest topic  
        sfn.people["scott"].topics.page(1, :order => 'recently_created').first.subject  #=> "Here's to Rene *Cheers*"
        

The interesting piece is that only made one http call: https://api.getsatisfaction.com/people/scott/topics?order=recently_created

Installing the Rubygem

sudo gem install ruby-satisfaction

Getting the Source Code

This library is hosted on github: https://github.com/nullstyle/ruby-satisfaction/tree/master You can also download a tarball of the latest code here: https://github.com/nullstyle/ruby-satisfaction/tarball/master

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. It contains the configuration and cache information.

The Satisfaction object provides access to several "Resource Collection" through which you get at the data in the system. These root level collections are:

• companies
• people
• topics
• replies
• tags
• products

These resource collections are acted upon by two fundamental methods: get, and page. get is used to retrieve a singular item such as:

sfn.people.get("scott")  #=> <person>
        

The returned object is a Resource, whose behavior is described below under the Resources headingpage, conversely retrieves a single page of resources, like so:

sfn.topics.page(3, :order => 'most_flagged') #=> [<Topic>, <Topic>, ...]

As you can see, the page method returns an array of Resource objects. Please note that 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 access, it will load from the api, for example:

me = sfn.people["scott"]  #  no API call takes place, [] is an alias of get  
          
        # the load takes place during the following statement  
        puts me.name  # => "Scott Fleckenstein" 

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:

Oauth uses a token system to authenticate access to the API: please see: https://developers.getsatisfaction.com/docs/using_oauth to learn about getting an access token. Once an access token has been obtained you can use it like so:

sfn.set_consumer("consumerkey", "consumersecret")  
        sfn.set_token("token", "tokensecret")

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')