The Get Satisfaction API has several libraries available that you can leverage to more easily use the API. Notably, there are libraries written for Ruby, PHP and Python.
For you Ruby programmers, we've released a RubyGem that will let you quickly and easily access and extract data from the Get Satisfaction API. It is inspired by ActiveResource.
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.
Fixed in 0.6.2 Known issue: In the example above, the second sfn = Satisfaction.new is required because, otherwise, the topics would be scoped to issues created by Jargon.
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:
As you can see, there are many different ways in which you can access the data that is important to your application.
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:
In this example, tagline is the attribute being accessed.
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. Going back to our first example:
As an alternative, you can explicitly call load on a Resource to pull its attributes from the API.
The rubygem exposes two 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. 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.
Sometimes things don't work as expected. For example, you might be trying to post a topic without permission to do so. We raise exceptions for errors so that you can catch them like so:
Note: This is new as of version 0.6.0. Previous versions return http status codes if there were errors. This would make error conditions more difficult to pin down when using method chaining.
The PHP API Library provides a set of routines for fetching data from and posting data to Get Satisfaction. It includes functions for fetching companies, people, products, tags, and topics, as well as functions for writing back with an authorized Get Satisfaction account, include posting, starring and flagging topics.
In addition to this you need MySQL to turn on the caching features.
To use the library you only need to include Satisfaction.php, i.e. <?php require_once("Satisfaction.php"); (Remember to use the correct path to the file.)
To use the caching features you will need to have a MySQL database with the following schema installed:
Every object in the Get Satisfaction API has an ID, which is a URL that uniquely identifies it. This ID can be used to fetch a representation of the object over HTTP. Because these IDs can be quite long, each one is also identified by a numeric ID distinguishing it from others of the same type; this is called the object's sfn:id or sfn_id. For example, the number 89521 is the sfn:id of a topic, but it might also be the sfn:id of a company, a person, or some other kind of object.
Many functions in the PHP Get Satisfaction API library accept just the ID or just the sfn:id of an object. Some functions accept one or the other, auto-detecting the sort of ID it has been given. Which type of ID a function accepts is made clear in its documentation.
Each function has a short comment describing its behavior in Satisfaction.php.
| Function | Arguments | Note |
|---|---|---|
| company_hcard | $company_id | Returns the vCard data of a company; it accepts an ID or an sfn:id. |
| company_name | $company_id | Returns the name of a company, given $company_id as either kind of ID. |
| Function | Arguments | Note |
|---|---|---|
| get_person | $url | Returns the vCard data for a person, given by URL (including an ID). |
| get_me_person | $consumer_data, $session_creds | Given OAuth session credentials $session_creds, it returns the vCard data for the user authorized under those credentials. $consumer_data argument gives the OAuth consumer data, which is provided when you sign up to use the Get Satisfaction API. |
| get_person_from_string | $str | vCard data for an individual person can include the fields fn, photo, URL, role, and canonical_name. The fn field is the user's full name, which may be in use by other users. The canonical_name is a string that uniquely identifies the person; it can be seen as the person's primary key. |
| employee_list | $company_sfnid | Returns a list of employees for given the company (having sfn:id $company_sfnid), in the form of minimal vCards. These "minimal" vCards need only contain the fields URL and role; hence the employees function is generally more useful. |
| employees | $company_sfnid | Returns a list of employees of the given company, as full-fledged vCards, containing all the usual person fields as well as role and role_name (see below). |
| get_person_role | $company_sfnid, $person_url | Returns the role of the given person at the given company, as a pair list ($role, $role_name) |
Note: The role_name field is a human-readable string describing the role; the role field is a token that identifies the role uniquely; currently the only roles are company_admin, company_rep and employee. Distinct roles may have the same human-readable role_name. A person may or may not have a role at a given company, and may have roles at more than one company. Thus "role" and "role_name" fields are only included in vCards returned by the employees() function.
| Function | Arguments | Note |
|---|---|---|
| product_list | $company_sfnid | Returns a list of the products associated with the given company. |
| products | $company_sfnid | Returns a list of the products associated with the given company, as product records. |
| get_product | $url | Fetches a product from $url, which may be an ID. |
Note: Product records have fields name, uri, and image.
| Function | Arguments | Note |
|---|---|---|
| tags | $url | Returns the tags found at $url. |
| Function | Arguments | Note |
|---|---|---|
| topic | $company_sfnid, $topic_id | Fetches all the data for a single topic by ID. |
| topics | $company_sfnid, $options, $at_least | Fetches a list of at least $at_least topics (defaulting to at least 1) under company $company_sfnid, according to the criteria specified in $options. The option can be 'product', 'tag', 'query', 'person', 'followed', or 'related'. It can also contain any of the options style and frequently_asked. If left empty it returns all the topics for the company. |
The result of topic is an associative array containing:
repliesparticiptagsThe result of topics is an associative array containing:
topicstotalsThe 'updated' field (the date of last update, in epoch format) also drives 'updated_relative' (a string like "45 minutes ago") and 'updated_formatted' (something like "June 1, 2008") which are useful for use in the templates. Note that the first item in the 'replies' array is different: it is the "head" or "lead_item", the post the started the topic. It has different properties than the other items.
There are some fields available for each item which need to be separately fetched and thus could be expensive. To make this information available without paying the cost by default, there is a set of extra functions which modify a feed by adding in this additional information. These functions include resolve_authors and resolve_companies.
I dealt with this by adding an additional call that modifies the array, populating it with the additional data. The example is "resolve_companies" which fetches company data for each topic in a topics feed. I intend to use this technique to deal with such cases in the future.
| Function | Arguments | Note |
|---|---|---|
| thread_items | $feed, $root | Given a feed as returned by topic(), convert it into "threaded" form. This means that the items in the resulting array are just the top-level replies; each of these has a 'replies' field which in turn contains a list of subordinate replies, formatted just as in the input. The $root parameter is the ID of the root item in the feed. |
| flatten_threads | $items | Given a threaded feed as returned by thread_items(), flatten it to a list by appending an item's replies after that item in the returned feed. This can be useful when preparing a threaded topic feed for use by a template; the flattened structure may be easier to use. The threading structure is still indicated by means of the 'in-reply-to' field of each item. As a convenience, the last item in each sub-thread is marked with a true value in a field thread_end. |
| filter_promoted | $replies | Filters a list of replies to the promoted items only, returning a pair of the company-promoted items and the star-promoted items, respectively. |
| company_partition | $company_hcard, $topics | Given a company, specified by its vCard, and a list $topics, separate $topics into those that partain to the given company and those that do not. The result is a pair list($company_topics, $other_topics). |
All posting operations use the OAuth standard and depend on having the authorization of a Get Satisfaction user account. OAuth provides a way for a user to authorize an API client to post on behalf of its account.
All OAuth requests are made on the basis of a "consumer key and secret," which are provided when you register to use the Get Satisfaction API. Each of the OAuth-related calls in this library accepts a $consumer_data parameter which is formatted as follows:
oauthed_request($consumer_data, $method, $url, $creds, $req_params, $query_params);
Arguments $method and $url specify the HTTP method to apply and the URL to apply it to. The $req_params specifies any additional parameters to the request—these are passed directly to the HTTP_Request object. The $query_params argument specifies additional URL query-string parameters (for a GET request) or request-body parameters (for a POST request).
The $creds argument gives the OAuth credentials of the user on whose behalf you are making the request. For example, to post a new topic as authored by a given user, use the credentials of that user. The $creds argument should be an array with fields 'token' and 'token_secret', containing the respective parts of the OAuth credentials.
get_oauth_request_token($consumer_data)
The result is a pair array($token, $token_secret) which can be used later, when the user returns from the authorization process, to identify the user. You might store this pair of tokens together with the user's cookie, so that you can match the ultimate authorization with a user session.
After obtaining the request_token, you should redirect the user to the URL provided by the oauth_authorization_url function, below, to permit the user to authorize that token.
oauth_authorization_url($token, $callback_url)
Returns a URL at which the user can authorize (or deny) access to the given token. If the user authorizes the token, he or she will be redirected to the given $callback_url, with an additional CGI parameter, oauth_token, whose value is the $token passed in.
For example, if the $token were 6cx2haob33pl and the $callback_url were
http://example.com/handle-oauth-return.php?foo=bar
Then, upon successful authorization, the user would be redirected to
http://example.com/handle-oauth-return.php?foo=bar&oauth_token=6cx2haob33pl
You can then use the request token and secret (as returned from get_oauth_request_token) to fetch the OAuth access token, using the get_oauth_access_token. Note the distinction between a request token and an access token: The request token is fetched before authorization, and is used to request authorization; the access token is fetched after authorization, and is used for all of that user's OAuth requests (such as posting a topic) during a the given session.
get_oauth_access_token($consumer_data, $request_token, $request_token_secret)
The access token can be used for writing back to Get Satisfaction by passing it to the oauthed_request function.
Once a user has authorized a request token, fetch an access token by calling get_oauth_access_token with the request token and secret that was returned by get_oauth_request_token for that particular user. This returns a new pair array($token, $token_secret) which constitutes a value for the $creds argument to oauthed_request. Once you've fetched the access token, the original request token for that user is no longer useful.
For its internal use, and for the convenience of library users, the library offers three levels of logging, (debug, message, and error) which can be enabled or disabled using the globals.
$logging$verbose$debuggingThe logging routines are as follows:
error($str)$str to the log as an error message.message($str)$str to the log as an informational message.debug($str)$str to the log as a debugging message.Developed by Graham Ashton, this is an in-progress project that is building a wrapper for the Get Satisfaction library. This library is open to community contributions Full details on the GitHub project page.