Project

popit

0.0
Repository is archived
No commit activity in last 3 years
No release in over 3 years
A Ruby wrapper for the PopIt API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

>= 0
~> 3.1.0

Runtime

~> 0.10.0
 Project Readme

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