Ruby gem that wraps the PopIt API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.gitignore
.rspec
.travis.yml
.yardopts
Gemfile
LICENSE
README.md
Rakefile
popit.gemspec

README.md

The PopIt API Ruby Gem

A Ruby wrapper for the PopIt API, which allows you to create, read, update and delete documents from PopIt.

Gem Version Build Status Coverage Status Code Climate

Installation

gem install popit

API Examples

First, require the PopIt gem:

require 'popit'

Then, create an API client for PopIt:

api = PopIt.new(:instance_name => 'demo')

You can pass these options to PopIt.new:

  • :instance_name the PopIt instance, usually the first part of the domain name
  • :host_name the PopIt API's host name – defaults to "popit.mysociety.org"
  • :port the PopIt API's port – defaults to 80
  • :version the PopIt API version – defaults to "v0.1"
  • :apikey an API key – if blank, the API will be read-only
  • :max_retries the number of times to retry the API in case of errors - defaults to 0

For brevity, we only show examples below for persons documents, but you can use the same code to operate on organizations and memberships by substituting organizations or memberships for persons.

More documentation at RubyDoc.info.

Read

Get one page of people (default 30 per page):

api.persons.get

Get a different number of people per page (maximum 100 per page):

api.persons.get(:per_page => 100)

Get another page of people:

api.persons.get(:page => 2)

Get one person:

api.persons('47cc67093475061e3d95369d').get

Search

Read the PopIt API documentation for details.

api.search.persons.get(:q => 'name:"John Doe"')

Create

response = api.persons.post(:name => 'John Doe')
id = response['id']

Update

api.persons(id).put(:id => id, :name => 'Jane Doe')

Delete

success = api.persons(id).delete

Error Handling

You will raise a PopIt::PageNotFound exception if you attempt to access an instance, API version, collection or document that doesn't exist. You will raise a PopIt::NotAuthenticated exception if you attempt to create, update or delete a document without authenticating. In other error cases, you will raise a generic PopIt::Error exception.

The exception's message will be the same as from the PopIt API.

require 'popit'
api = PopIt.new(:instance_name => 'demo')
api.persons.get('foo') # raises PopIt::PageNotFound with "page not found"

Running Tests

To run the tests:

export INSTANCE_NAME=YOUR_POPIT_INSTANCE_NAME
export POPIT_API_KEY=YOUR_POPIT_API_KEY
bundle exec rake

If you care about the data in an instance, do not use that instance to run tests!

Copyright (c) 2011 James McKinney, released under the MIT license