Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Using The API

lukebaker edited this page · 4 revisions

Pairwise is the API powering All Our Ideas, a research project to develop a new form of social data collection that combines the best features of quantitative and qualitative methods. Using the power of the web, we are creating a data collection tool that has the scale, speed, and quantification of a survey while still allowing for new information to “bubble up” from respondents as happens in interviews, participant observation, and focus groups.

The API facilitates the creation of clients that can generate questions, populate them with choices containing arbitrary data, present binary choices to users, and analyze the results. To begin using the API, first install the API and add an API user to pairwise ./bin/rake util:useradd[,passwordgoeshere]

Once you’ve installed the API there are several ways you can use it. Each are described below:

  • use a sample API client
  • create your own Rails application to act as the client
  • run your own installation of the code
  • create your own application that issues API requests via the HTTP protocol to the pairwise API.

Launching the Sample Client

Make sure you have git installed, then fetch and configure the client. The following should work for a Debian/Ubuntu system:

$ git clone git://
cd sample-pairwise-video-client/

Now enter the email address and password of the API user and pairwise API host in sample-pairwise-video-client/config/environments/development.rb:


Get all of the dependencies required to use rails and build the gems:

bundle install --path vendor/

and launch a development server:

bundle exec ./script/server -p 3000

You should now be able to access the site in your browser at “http://localhost:3000”.

Getting started with Rails:

The API was written to be used with ActiveResource, so creating a client with Rails is very easy. To get started, simply create the following models inheriting from ActiveResource and enter the credentials for your API user:

class Question < ActiveResource::Base = API_HOST
   self.user = API_USER_EMAIL
   self.password = API_USER_PASSWORD
   attr_accessor :name, :question_text, :ideas, :url, :information, :email, :password
class Prompt < ActiveResource::Base = "#{API_HOST}/questions/:question_id/"
   self.user = API_USER_EMAIL
   self.password = API_USER_PASSWORD
   attr_accessor :name, :question_text, :question_ideas

Now you’re ready to create and start voting on your own idea marketplace. First, create a new question:

>> q = Question.create(:visitor_identifier => "owner", 
                       :name => "new question",
                       :ideas => "foo\nbar\nbaz\n")
=> #<Question:0xb6870224 ... >

Ask the newly created question for the next prompt to be displayed and fetch it:

>> q = Question.find(, :params => { :with_prompt => true,
                                        :with_appearance => true,
                                        :visitor_identifier => 'owner' })
=> #<Question:0xb67d849c ... >
>> p = Prompt.find(q.picked_prompt_id, :params => { :question_id => })
=> #<Prompt:0xb67b50c8 ... >

Cast a vote on the retrieved prompt, verifying that it was counted:

>> q.votes_count
=> 0
>>, :question_id =>, :vote => { :direction => "left" })
=> #<Net::HTTPOK 200 OK  readbody=true>
>> q.reload.votes_count
=> 1

Check the complete API Documentation for a full list of available calls.

Running Code

Review the installation documentation

Issuing API calls via HTTP

Both cookie-based RESTful and HTTP basic authentication are supported at the moment. Requests should include either the ‘Authorization’ header with a colon-separated, base-64 encoded user:password pair, or the ‘remember-token’ cookie set to the 40-character hash provided at login. Each request should also include a cookie identifying the user’s session.


HTTP Basic authentication:

Request a list of questions:


HTTP/1.1 200 OK
Set-Cookie: _rebirth_session_key=BAh7BzoP...d52ade1d; path=/; HttpOnly

<?xml version="1.0" encoding="UTF-8"?>
<questions type="array">

Subsequent requests should include the ‘_rebirth_session_key’ cookie. E.g. to create a new question:

$ curl -X 'POST' -i -u "<API_USER_EMAIL>:<API_USER_PASSWORD>" <API_URL>/questions.xml \
> -H "Content-Type: application/xml" \
> -H "Cookie: rebirth_session_key=BAh7BzoP...d52ade1d" \
> -d '<?xml version="1.0" encoding="UTF-8"?> \
> <question> \
>   <visitor-identifier>owner</visitor-identifier> \
>   <name>new question</name> \
>   <ideas>foo\n\bar\n\baz</ideas> \
> </question>'

HTTP/1.1 200 OK 

<?xml version="1.0" encoding="UTF-8"?>

RESTful authentication

$ curl -i -X 'POST' -H 'Content-Type: application/xml' API_HOST/session.xml \
-d '<?xml version="1.0" encoding="UTF-8"?> \
<session> \
  <email>API_USER_EMAIL</email> \
  <password>API_USER_PASSWORD</password> \
</session>' \

HTTP/1.1 302 Found 
Set-Cookie: remember_token=0abaf22c ... fa291244; path=/; expires= ...
Set-Cookie: _rebirth_session_key=BAh7BzoP ... c0bb455b; path=/; HttpOnly

<html><body>You are being <a href="API_HOST/">redirected</a>.</body></html>

Subsequent requests need to include both the ‘remember_token’ and ‘_rebirth_session_key’ cookies:

 curl -X 'POST' -i API_HOST/questions.xml \
-H 'Cookie: remember_token=0abaf22c ... fa291244' \
-H 'Cookie: _rebirth_session_key=BAh7BzoP ... c0bb455b' \
-H 'Content-Type: application/xml' \
-d '<?xml version="1.0" encoding="UTF-8"?> \
<question> \
  <visitor-identifier>owner</visitor-identifier> \
  <name>new question</name> \
  <ideas>foo\nbar\nbaz</ideas> \

HTTP/1.1 200 OK 

<?xml version="1.0" encoding="UTF-8"?>
Something went wrong with that request. Please try again.