popit 0.0.1 → 0.0.2

data/README.md

@@ -2,7 +2,6 @@
 
 A Ruby wrapper for the [PopIt](http://popit.mysociety.org/) API, which allows you to create, read, update and delete items from PopIt.
 
-[![Build Status](https://secure.travis-ci.org/opennorth/popit-ruby.png)](http://travis-ci.org/opennorth/popit-ruby)
 [![Dependency Status](https://gemnasium.com/opennorth/popit-ruby.png)](https://gemnasium.com/opennorth/popit-ruby)
 [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/opennorth/popit-ruby)
 
@@ -12,19 +11,19 @@ A Ruby wrapper for the [PopIt](http://popit.mysociety.org/) API, which allows yo
 
 ## API Examples
 
-Require the PopIt gem:
+First, require the PopIt gem:
 
 ```ruby
 require 'popit'
 ```
 
-Create an API client:
+Then, create an API client for PopIt:
 
 ```ruby
 api = PopIt.new :instance_name => 'demo'
 ```
 
-You can pass the options:
+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"
@@ -33,7 +32,7 @@ You can pass the options:
 * `:user` a user name – if blank, the API will be read-only
 * `:password` the user's password
 
-For brevity, we only show examples for `person` items, but you use the same code to operate on organisations and positions by substituting `organisation` or `position` for `person`.
+For brevity, we only show examples below for `person` items, but you can use the same code to operate on organisations and positions by substituting `organisation` or `position` for `person`.
 
 More documentation at [RubyDoc.info](http://rdoc.info/gems/popit/PopIt).
 
@@ -53,12 +52,14 @@ response = api.person('47cc67093475061e3d95369d').get
 p response['result']
 ```
 
-You can search...
+You can also search for...
 
 * people by slug, name or summary
 * organisations by slug or name
 * positions by title, person or organisation
 
+For example:
+
 ```ruby
 response = api.person.get :name => 'John Doe'
 p response['results']
@@ -74,30 +75,30 @@ id = response['result']['_id']
 ### Update
 
 ```ruby
-response = api.person('47cc67093475061e3d95369d').put :name => 'Jane Doe'
+response = api.person(id).put :name => 'Jane Doe'
 p response['result']
 ```
 
 ### Delete
 
 ```ruby
-success = api.person('47cc67093475061e3d95369d').delete
+success = api.person(id).delete
 ```
 
 ## Error Handling
 
-If you:
+If you attempt to:
 
-* attempt to read an item that doesn't exist
-* attempt to create, update or delete an item without authenticating
-* attempt to operate on something other than people, organisations and positions
+* read an item that doesn't exist
+* create, update or delete an item without authenticating
+* operate on something other than people, organisations and positions
 
-you will raise a `PopIt::Error` exception. The exception's message will be the error message from the PopIt API.
+you will raise a `PopIt::Error` exception. The exception's message will be the same as from the PopIt API.
 
 ```ruby
 require 'popit'
 api = PopIt.new :instance_name => 'demo'
-api.person.get 'foo' # raises PopIt::Error
+api.person.get 'foo' # raises PopIt::Error with {"error":"page not found"}
 ```
 
 ## Running Tests

data/lib/popit/version.rb

@@ -1,3 +1,3 @@
 class PopIt
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/popit.rb

@@ -3,6 +3,20 @@ require 'yajl'
 
 # A Ruby wrapper for the PopIt API.
 #
+# Instead of writing the path to an API endpoint, you can use method chaining.
+# For example:
+#
+#     require 'popit'
+#     api = PopIt.new :instance_name => 'demo'
+#     api.get 'person/john-doe'
+#
+# can be written as:
+#
+#     api.person('john-doe').get
+#
+# All methods and arguments between `api` and the HTTP method - in this case,
+# `get` - become parts of the path.
+#
 # @see https://github.com/mysociety/popit/blob/master/lib/apps/api/api_v1.js
 class PopIt
   class Error < StandardError; end
@@ -33,22 +47,38 @@ class PopIt
     @password      = opts[:password]
   end
 
-  def base_uri
-    "http://#{instance_name}.#{host_name}:#{port}/api/#{version}"
-  end
-
+  # Send a GET request.
+  #
+  # @param [String] path a path with no leading slash
+  # @param [Hash] opts key-value pairs for the query string
+  # @return the JSON response from the server
   def get(path, opts = {})
     request :get, path, opts
   end
 
+  # Send a POST request.
+  #
+  # @param [String] path a path with no leading slash
+  # @param [Hash] opts key-value pairs for the message body
+  # @return the JSON response from the server
   def post(path, opts = {})
     request :post, path, opts
   end
 
+  # Send a PUT request.
+  #
+  # @param [String] path a path with no leading slash
+  # @param [Hash] opts key-value pairs for the message body
+  # @return [nil] nothing
   def put(path, opts = {})
     request :put, path, opts
   end
 
+  # Send a DELETE request.
+  #
+  # @param [String] path a path with no leading slash
+  # @param [Hash] opts key-value pairs for the query string
+  # @return [Hash] an empty hash
   def delete(path, opts = {})
     request :delete, path, opts
   end
@@ -56,7 +86,7 @@ class PopIt
 private
 
   def request(http_method, path, opts = {})
-    path = "#{base_uri}/#{path}"
+    path = "http://#{instance_name}.#{host_name}:#{port}/api/#{version}/#{path}"
 
     response = case http_method
     when :get

data/spec/popit_spec.rb

@@ -4,7 +4,7 @@ require 'yaml'
 
 # We don't want to test the PopIt API. We want to check that the wrapper works.
 #
-# @see https://github.com/mysociety/popit-python/blob/master/test.py
+# @see https://github.com/mysociety/popit/blob/master/lib/apps/api/api_v1.js
 describe PopIt do
   let :unauthenticated do
     PopIt.new :instance_name => 'tttest'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: popit
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors: