festivals_lab 0.0.1 → 0.0.2

data/.gitignore

@@ -0,0 +1 @@
+/pkg/

data/CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing #
+
+Thanks for reading this! Contributions are very welcome via Github pull request, but first bear in mind a couple of general guidelines that I'm starting out with:
+
+* The gem is designed to lightly wrap the Festivals Lab API, and not be too smart about processing the input or output. The API is currently in beta and behaviour is subject to change
+
+* Create separate pull requests for each feature, and try not to include changes that aren't relevant to the request (for example, `.gitignore`)
+
+## Getting started ##
+
+To start hacking at the code, it should be as simple as checking out the code and running the tests
+
+    > git clone https://github.com/gareth/festivals_lab.git
+    > cd festivals_lab
+    > bundle
+    > bundle exec rake

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    festivals_lab (0.0.1)
+    festivals_lab (0.0.2)
 
 GEM
   remote: http://rubygems.org/

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2013 Gareth Adams
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+# Festivals Lab API #
+
+An unofficial library to access festival data from the Edinburgh Festivals Innovation Lab API
+
+## Description ##
+
+Festivals Lab is an open data initiative which provides free access to the events of the 12 annual Edinburgh festivals.
+
+The `festivals_lab` gem wraps the API and ties it with a Ruby bow
+
+## Compatibility ##
+
+* As an alpha, `festivals_lab` is only developed and tested against Ruby 1.9.3 (other rubies should work, but run the tests first).
+* There are no external dependencies for use other than the Ruby standard library.
+
+## Installation ##
+
+Install festivals_lab like any other ruby gem:
+
+    > gem install festivals_lab
+
+Or, to use it in a project with Bundler, add this to your Gemfile:
+
+    gem 'festivals_lab'
+
+…and then run the bundle install command from your shell:
+
+    > bundle
+
+## Usage ##
+
+To use the FestivalsLab API you will need an API key, which can be obtained from the [Festivals Lab website][gettingstarted].
+
+The parameters for library method calls match the [official documentation][querying], with the following considerations:
+
+* The `key` and `signature` parameters are automatically added for you based on your authentication details, so there is no need to supply those to each API call.
+* All parameters should be passed as `String` or `Numeric` (e.g. `Integer` or `Float`), specifically `Date`s aren't converted into the API's expected format yet
+* The library exclusively requests JSON responses from the API, and the `pretty` parameter is invalid.
+
+  [gettingstarted]: http://api.festivalslab.com/documentation#gettingstarted
+  [querying]: http://api.festivalslab.com/documentation#Querying the API
+
+### Sample usage ###
+
+    api = FestivalsLab.new("xxAPIAccessKeyxx", "xxAPISecretKeyxxxxAPISecretKeyxx")
+
+    api.events # The first page of events (using the API's default of 25 per page)
+
+    api.events(festival: 'book', size: 50, from: 100)
+
+    api.events(festival: 'fringe', post_code: 'EH1', price_to: 5)
+
+The library returns the data as returned from the API, run through a JSON parser
+
+### License ###
+
+This software is open source and is licensed under the MIT license.
+
+See the LICENSE file for more details
+
+### Contributing ###
+
+See the CONTRIBUTING file

data/lib/festivals_lab/version.rb

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

data/lib/festivals_lab.rb

@@ -4,14 +4,14 @@ require 'openssl' # Provides HMAC-SHA1
 
 class FestivalsLab
 
-  attr_accessor :access_token, :access_key
+  attr_accessor :access_key, :secret_token
 
   SCHEME = "http"
   HOST = "api.festivalslab.com"
 
-  def initialize access_token, access_key
-    @access_token = access_token
+  def initialize access_key, secret_token
     @access_key   = access_key
+    @secret_token = secret_token
   end
 
   def events params = {}
@@ -36,47 +36,54 @@ class FestivalsLab
 
     raise ArgumentError, "Unexpected events parameter: #{invalid_keys.join ", "}" if invalid_keys.any?
 
-    request '/events', params
+    FestivalsLab.request access_key, secret_token, '/events', params
   end
 
-  def request endpoint, params = {}
-    uri = signed_uri endpoint, params
-    Net::HTTP.start(uri.host, uri.port) do |http|
-      request = Net::HTTP::Get.new uri.request_uri
-      request['Accept'] = 'application/json'
-      response = http.request request
-      if Net::HTTPSuccess === response
-        JSON.parse(response.body)
-      else
-        raise ApiError.new(response)
+  def event uuid
+    FestivalsLab.request access_key, secret_token, "/event/#{uuid}"
+  end
+
+  class << self
+    def request access_key, secret_token, endpoint, params = {}
+      uri = FestivalsLab.signed_uri access_key, secret_token, endpoint, params
+      Net::HTTP.start(uri.host, uri.port) do |http|
+        request = Net::HTTP::Get.new uri.request_uri
+        request['Accept'] = 'application/json'
+        response = http.request request
+        if Net::HTTPSuccess === response
+          JSON.parse(response.body)
+        else
+          raise ApiError.new(response)
+        end
       end
     end
-  end
 
-  def signed_uri endpoint, params = {}
-    params = params.dup
-    raise Error, "Missing API access key" unless access_key
-    raise Error, "Missing API access token" unless access_token
-    # Start with a generic URI representing just the path
-    # This is convenient because the URI represents the string which gets signed
-    uri = URI(endpoint)
-
-    params[:key] = access_token
-    uri.query = URI.encode_www_form(params)
-
-    params[:signature] = self.signature uri.to_s
-    uri.query = URI.encode_www_form(params)
-
-    uri.scheme = SCHEME
-    uri.host   = HOST
-    # Now the URI has a scheme we can convert it to an actual URI::HTTP
-    URI.parse(uri.to_s)
-  end
+    def signed_uri access_key, secret_token, endpoint, params = {}
+      params = params.dup
+      raise Error, "Missing API access key" unless access_key
+      raise Error, "Missing API secret token" unless secret_token
+      # Start with a generic URI representing just the path
+      # This is convenient because the URI represents the string which gets signed
+      uri = URI(endpoint)
+
+      params[:key] = access_key
+      uri.query = URI.encode_www_form(params)
 
-  def signature url
-    OpenSSL::HMAC.hexdigest 'sha1', access_key, url
+      params[:signature] = FestivalsLab.signature secret_token, uri.to_s
+      uri.query = URI.encode_www_form(params)
+
+      uri.scheme = SCHEME
+      uri.host   = HOST
+      # Now the URI has a scheme we can convert it to an actual URI::HTTP
+      URI.parse(uri.to_s)
+    end
+
+    def signature secret_token, url
+      OpenSSL::HMAC.hexdigest 'sha1', secret_token, url
+    end
   end
 
+
   Error = Class.new(StandardError)
   ArgumentError = Class.new(::ArgumentError)
   ApiError = Class.new(StandardError) do

data/test/lib/test_festivals_lab.rb

@@ -21,13 +21,13 @@ describe FestivalsLab do
     it "sets an access token" do
       api = FestivalsLab.new "123", nil
 
-      api.access_token.must_equal "123"
+      api.access_key.must_equal "123"
     end
 
     it "sets an access key" do
       api = FestivalsLab.new nil, "456"
 
-      api.access_key.must_equal "456"
+      api.secret_token.must_equal "456"
     end
   end
 
@@ -84,7 +84,27 @@ describe FestivalsLab do
     end
   end
 
-  describe "#request" do
+  describe "#event" do
+    it "requests the event from the API" do
+      stub = stub_http_request(:get, %r{//api\.festivalslab\.com/event/00000000000000000000000000000000deadbeef})
+        .to_return(@successful_response)
+
+      response = @api.event '00000000000000000000000000000000deadbeef'
+
+      assert_requested(stub)
+    end
+
+    it "returns the parsed event" do
+      stub = stub_http_request(:get, %r{//api\.festivalslab\.com/event/00000000000000000000000000000000deadbeef})
+        .to_return(@successful_response)
+
+      response = @api.event '00000000000000000000000000000000deadbeef'
+
+      assert_equal [{}], response
+    end
+  end
+
+  describe "request" do
     before do
       @uri = "http://api.festivalslab.com/events?key=123&signature=742969faae86a4ba4223c7d93d05ead4b1397c23"
     end
@@ -92,7 +112,7 @@ describe FestivalsLab do
     it "makes a request to the signed endpoint URI" do
       stub_request(:get, @uri).to_return(@successful_response)
 
-      @api.request '/events'
+      FestivalsLab.request @api.access_key, @api.secret_token, '/events'
 
       assert_requested(:get, @uri)
     end
@@ -101,7 +121,7 @@ describe FestivalsLab do
       stub = stub_http_request(:get, @uri)
         .to_return(@successful_response)
 
-      response = @api.request '/events'
+      response = FestivalsLab.request @api.access_key, @api.secret_token, '/events'
 
       assert_equal [{}], response
     end
@@ -110,32 +130,32 @@ describe FestivalsLab do
       stub = stub_http_request(:get, @uri)
         .to_return(@failed_response)
 
-      lambda { @api.request '/events' }.must_raise(FestivalsLab::ApiError)
+      lambda { FestivalsLab.request @api.access_key, @api.secret_token, '/events' }.must_raise(FestivalsLab::ApiError)
     end
   end
 
-  describe "#signed_uri" do
+  describe "signed_uri" do
     it "requires an access key to be set" do
-      @api.access_key = nil
-      lambda { @api.signed_uri('/events') }.must_raise(FestivalsLab::Error, "Missing API access key")
+      @api.secret_token = nil
+      lambda { FestivalsLab.signed_uri(@api.access_key, @api.secret_token, '/events') }.must_raise(FestivalsLab::Error, "Missing API access key")
     end
 
     it "requires an access token to be set" do
-      @api.access_token = nil
-      lambda { @api.signed_uri('/events') }.must_raise(FestivalsLab::Error, "Missing API access token")
+      @api.access_key = nil
+      lambda { FestivalsLab.signed_uri(@api.access_key, @api.secret_token, '/events') }.must_raise(FestivalsLab::Error, "Missing API access token")
     end
 
     it "appends the correct signature to the request URI" do
-      uri = @api.signed_uri('/events', {:key => 123})
+      uri = FestivalsLab.signed_uri(@api.access_key, @api.secret_token, '/events', {:key => 123})
       uri.must_be_kind_of(URI)
       uri.to_s.must_equal 'http://api.festivalslab.com/events?key=123&signature=742969faae86a4ba4223c7d93d05ead4b1397c23'
     end
   end
 
-  describe "#signature" do
+  describe "signature" do
     it "calculates the HMAC-SHA1 signature based on the access key" do
       ## Because `OpenSSL#HMAC.hexdigest('sha1', '456', '/events?key=123')` # => '742969faae86a4ba4223c7d93d05ead4b1397c23'
-      @api.signature('/events?key=123').must_equal '742969faae86a4ba4223c7d93d05ead4b1397c23'
+      FestivalsLab.signature(@api.secret_token, '/events?key=123').must_equal '742969faae86a4ba4223c7d93d05ead4b1397c23'
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: festivals_lab
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -66,9 +66,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .gitignore
 - .rvmrc
+- CONTRIBUTING.md
 - Gemfile
 - Gemfile.lock
+- LICENSE
 - README.md
 - Rakefile
 - festivals_lab.gemspec
@@ -90,7 +93,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2264928236337400198
+      hash: 4234472854470534461
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -99,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2264928236337400198
+      hash: 4234472854470534461
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24