Using The API

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[[email protected],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 allourideas.org 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://github.com/allourideas/sample-pairwise-video-client.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:

API_HOST = "http://api.allourideas.org"
PAIRWISE_USERNAME = "API_USER_EMAIL"
PAIRWISE_PASSWORD = "API_USER_PASSWORD"

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:

#/app/models/question.rb
class Question < ActiveResource::Base
   self.site = API_HOST
   self.user = API_USER_EMAIL
   self.password = API_USER_PASSWORD
   attr_accessor :name, :question_text, :ideas, :url, :information, :email, :password
end

#/app/models/prompt.rb
class Prompt < ActiveResource::Base
   self.site = "#{API_HOST}/questions/:question_id/"
   self.user = API_USER_EMAIL
   self.password = API_USER_PASSWORD
   attr_accessor :name, :question_text, :question_ideas
end

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

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

>> q.votes_count
=> 0
>> p.post(:vote, :question_id => q.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 allourideas.org 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.

Examples:

HTTP Basic authentication:

Request a list of questions:

$ curl -i -u "<API_USER_EMAIL>:<API_USER_PASSWORD" \
<API_URL>/questions.xml

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

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

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"?>
<question>
   ...
</question>

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> \
</question>'

HTTP/1.1 200 OK 
...

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