marvel_api 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9133e1fdec31b9c7841f6e23729cd412a10aa310
-  data.tar.gz: 96b3b3becbda0afe29f29938444b042f7ec1d974
+  metadata.gz: f2b4c452319c1d34f3de718e532fe92890ef8440
+  data.tar.gz: 72b6f58e63a3b610e83991105f5e92894c7c9094
 SHA512:
-  metadata.gz: 9410f5d4c555781945893a5e618ecfdef1dc48a4bb7d522a8b2f9b6af5f3bcab6d669aac104d88f67ad855e2790796d41f249d09686f56e88af58b323b9325d0
-  data.tar.gz: 85b4a94ee6394355350f55819009b6c00c0687b14abf1f84384bba2780a02752edbbd3be441cd375e0bc8e84cfc9628c51fd3c33f1c7c17e6d0a771a5537ac56
+  metadata.gz: ee6167a8840a5ad32e71afcce65345442ae1e5d4706ca561e5930066dac0b1213606e05b02472c6c8df60d03e6e998935778dfd83869f93c3a230428f6290ab7
+  data.tar.gz: 2aa7a6f153b0e2349c710fe99641f7916fc965c7f9d2e885c9e651d2a53ed65f4ea61e15b7350d750a5942db60a3ec99a18bce63fba1fd6a142dbb6220686fff

data/.document

@@ -2,4 +2,4 @@ lib/**/*.rb
 bin/*
 - 
 features/**/*.feature
-LICENSE.txt
+LICENSE.txt

data/.rspec

@@ -1 +1,2 @@
---color
+--color
+--order random

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - 2.1.1
+  - 2.1.2
+  - ruby-head

data/Gemfile

@@ -1,8 +1,8 @@
 source 'https://rubygems.org'
 
-gem 'faraday'
-gem 'faraday_middleware'
-gem 'hashie' 
+gem 'faraday', '>= 0.7', '< 0.10'
+gem 'faraday_middleware', '>= 0.8', '< 0.10'
+gem 'hashie', '>= 0.4.0'
 
 group :development do
   gem 'pry'
@@ -11,5 +11,12 @@ group :development do
   gem 'rdoc', '~> 3.12'
   gem 'bundler', '~> 1.0'
   gem 'jeweler', '~> 1.8.7'
-  gem 'simplecov'
 end
+
+group :test do
+  gem 'rspec'
+  gem 'webmock'
+  gem 'coveralls', require: false
+  gem 'simplecov', require: false
+  gem 'guard-rspec', require: false
+end

data/Guardfile

@@ -0,0 +1,5 @@
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -17,4 +17,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,10 +1,12 @@
 # marvel_api
+[![Build Status](https://travis-ci.org/O-I/marvel.svg?branch=master)](https://travis-ci.org/O-I/marvel)
+[![Coverage Status](https://img.shields.io/coveralls/O-I/marvel.svg)](https://coveralls.io/r/O-I/marvel)
 
-Ruby bindings for the [Marvel API](http://developer.marvel.com/). Still under construction... Feel free to contribute! In the meantime, check out the [marvelite](https://github.com/antillas21/marvelite/) gem for something that's further along in development (and likely a lot stabler :-).
+Ruby bindings for the [Marvel API](http://developer.marvel.com/). In active development. Feel free to contribute! Need Ruby 1.9.2 support or don't like Faraday? Check out the [marvelite](https://github.com/antillas21/marvelite/) gem for an alternative. (-:
 
 ## Installation
 
-`gem install 'marvel_api'` or add `gem 'marvel_api'` to your Gemfile.
+`gem install 'marvel_api'` or add `gem 'marvel_api'` to your Gemfile and `bundle`.
 
 ## Configuration
 
@@ -21,7 +23,7 @@ end
 
 ## Usage
 
-Descriptions and examples of the supported actions are below. Note, all methods currently return a `Hashie:Mash` object if successful. For a more detailed explanation of available actions and an exhaustive list of acceptable query parameters, see Marvel's own developer [documentation](http://developer.marvel.com/docs). Each method described below links to the associated call in Marvel's interactive API tester.
+Descriptions and examples of the supported actions are below. Note, all methods currently return an `Array` of `Hashie::Mash` objects if successful; otherwise, a `Marvel::Response::Error` is returned. For a more detailed explanation of available actions and an exhaustive list of acceptable query parameters, see Marvel's own developer [documentation](http://developer.marvel.com/docs). Each method described below links to the associated call in Marvel's interactive API tester.
 
 ### Characters
 
@@ -119,7 +121,6 @@ Descriptions and examples of the supported actions are below. Note, all methods
 @client.creators
 @client.creators(firstName: 'Frank', lastName: 'Miller')
 @client.creators(lastNameStartsWith: 'Mo', limit: 20, offset: 20)
-
 ```
 
 - Fetches a single creator by id. [`GET /v1/public/creators/{creatorId}`](http://developer.marvel.com/docs#!/public/getCreatorIndividual_get_13)
@@ -309,6 +310,17 @@ Descriptions and examples of the supported actions are below. Note, all methods
 @client.story_series(126, titleStartsWith: 'Infinity')
 ```
 
+### Etags
+
+Most successful responses contain an `etag` attribute that can be used to check whether the content of the requested resource has remained the same since the last request. 
+
+```ruby
+thanos = @client.character(1009652)
+@client.character(1009652, etag: thanos.etag)
+```
+
+If the content has not changed, a `Marvel::Response::Error` with `code` 304 and `status` 'Not Modified' is returned and you can use your cached content knowing that it is up-to-date and that you saved some bandwidth. If the content has changed or the Etag is invalid, the resource you requested will be returned.
+
 ## Contributing to marvel_api
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.

data/Rakefile

@@ -12,15 +12,18 @@ end
 require 'rake'
 
 require 'jeweler'
+require './lib/marvel/version.rb'
 Jeweler::Tasks.new do |gem|
   # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
-  gem.name = "marvel_api"
-  gem.homepage = "http://github.com/O-I/marvel"
-  gem.license = "MIT"
+  gem.name = 'marvel_api'
+  gem.version = Marvel::Version
+  gem.homepage = 'http://github.com/O-I/marvel'
+  gem.license = 'MIT'
   gem.summary = %Q{Ruby bindings for the Marvel API}
-  gem.description = %Q{Marvel_API is a Ruby gem that lets you explore the Marvel Universe like never before.}
-  gem.email = "hore.rahul@gmail.com"
-  gem.authors = ["Rahul Horé"]
+  gem.description = %Q{Explore the Marvel Universe like never before.}
+  gem.email = 'hore.rahul@gmail.com'
+  gem.authors = ['Rahul Horé']
+  gem.required_ruby_version = '>= 1.9.3'
   # dependencies defined in Gemfile
 end
 Jeweler::RubygemsDotOrgTasks.new
@@ -35,10 +38,10 @@ task :default => :spec
 
 require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  version = Marvel::Version
 
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "marvel_api #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
-end
+end

data/lib/marvel/client.rb

@@ -19,22 +19,14 @@ module Marvel
     # Requests on the server side must be of the form
     # http://gateway.marvel.com/v1/comics/?ts=1&apikey=1234&hash=ffd275c5130566a2916217b101f26150
     # where ts is a timestamp
-    # where apikey is your public API key
-    # where hash is the MD5 hash of the concatenation of 
-    # ts, your private API key, and your public API key
+    #       apikey is your public API key
+    #       hash is the MD5 hash of the concatenation of
+    #       ts, your private API key, and your public API key
 
-    # So basic request form for all methods looks like
-    # Faraday.get("#{BASE_URL}#{path}#{id}#{stub}#{auth}").body
-    # e.g., get_comics_by_character_id
-    # Faraday.get("#{BASE_URL}characters/#{id}/comics#{auth}").body
+    # All methods return an Array of Hashie::Mash objects
+    # that represent the original JSON response
 
-    # TODO; MODULARIZE THIS!!!
-    # TODO; Refactor — tons of duplication
-
-    # All methods return a Hashie::Mash object
-    # representation of the original JSON response
-
-    # Characters: 
+    # Characters:
 
     # fetches lists of characters
     def characters(options = {})

data/lib/marvel/connection.rb

@@ -1,18 +1,26 @@
 require 'faraday_middleware'
+require_relative 'version'
 
 module Marvel
   module Connection
+
+    BASE_API_URL = 'https://gateway.marvel.com/v1/public/'
+    HEADERS = {
+                accept: 'application/json',
+                user_agent: "marvel_api gem #{Marvel::Version}"
+              }
+
     private
 
     def connection
       options = {
+        headers: HEADERS,
         ssl: { verify: false },
-        url: 'https://gateway.marvel.com/v1/public/'
+        url: BASE_API_URL
       }
 
       Faraday.new(options) do |connection|
         connection.use Faraday::Request::UrlEncoded
-        connection.use Faraday::Response::RaiseError
         connection.use Faraday::Response::Mashify
         connection.use Faraday::Response::ParseJson
         connection.adapter(Faraday.default_adapter)

data/lib/marvel/error.rb

@@ -0,0 +1,16 @@
+module Marvel
+  module Response
+    class Error < StandardError
+      attr_reader :code, :status
+
+      def initialize(response_hash)
+        @code = response_hash['code']
+        @status = response_hash['status'] || response_hash['message']
+      end
+
+      def to_s
+        "#{@code} #{@status}"
+      end
+    end
+  end
+end

data/lib/marvel/request.rb

@@ -1,5 +1,10 @@
+require_relative 'response'
+require_relative 'error'
+
 module Marvel
   module Request
+    include Marvel::Response
+
     def get(path, options = {})
       request(:get, path, options)
     end
@@ -7,24 +12,33 @@ module Marvel
     private
 
     def request(method, path, options = {})
+      etag = options.delete(:etag)
       response = connection.send(method) do |request|
         request.url(path, options.merge(auth))
+        request.headers['If-None-Match'] = etag if etag
+      end
+      prepare(response)
+    end
+
+    def prepare(response)
+      case response.status
+      when 200 then Marvel::Response.create(response.body)
+      when 304 then Marvel::Response::Error.new(
+                      { 'code' => 304, 'status' => 'Not Modified' })
+      else          Marvel::Response::Error.new(response.body)
       end
-      response.body
     end
 
-    def auth
-      ts = timestamp
-      hsh = hash(ts)
-      { ts: ts, apikey: api_key, hash: hsh }
+    def auth(nonce = timestamp)
+      { ts: nonce, apikey: api_key, hash: hash(nonce) }
     end
 
-    def hash(ts)
-      Digest::MD5.hexdigest(ts + private_key + api_key)
+    def hash(nonce)
+      Digest::MD5.hexdigest(nonce + private_key + api_key)
     end
 
     def timestamp
       Time.now.to_s
-    end    
+    end
   end
 end

data/lib/marvel/response.rb

@@ -0,0 +1,21 @@
+module Marvel
+  module Response
+    def self.create(response_hash)
+      results = response_hash.data.results.dup rescue response_hash
+      results.extend(self)
+      results.instance_exec do
+        @code   = response_hash.code
+        @status = response_hash.status
+        @etag   = response_hash.etag
+        @offset = response_hash.data.offset
+        @limit  = response_hash.data.limit
+        @total  = response_hash.data.total
+        @count  = response_hash.data.count
+      end
+      results
+    end
+
+    attr_reader :code, :status, :etag,
+                :offset, :limit, :total, :count
+  end
+end

data/lib/marvel/version.rb

@@ -0,0 +1,14 @@
+module Marvel
+  class Version
+    MAJOR = 0
+    MINOR = 2
+    PATCH = 1
+    PRE = nil
+
+    class << self
+      def to_s
+        [MAJOR, MINOR, PATCH, PRE].compact.join('.')
+      end
+    end
+  end
+end

data/marvel_api.gemspec

@@ -2,17 +2,17 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: marvel_api 0.2.0 ruby lib
+# stub: marvel_api 0.2.1 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "marvel_api"
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Rahul Hor\u{e9}"]
-  s.date = "2014-05-20"
-  s.description = "Marvel_API is a Ruby gem that lets you explore the Marvel Universe like never before."
+  s.date = "2014-07-02"
+  s.description = "Explore the Marvel Universe like never before."
   s.email = "hore.rahul@gmail.com"
   s.extra_rdoc_files = [
     "LICENSE.txt",
@@ -21,23 +21,83 @@ Gem::Specification.new do |s|
   s.files = [
     ".document",
     ".rspec",
+    ".travis.yml",
     "Gemfile",
+    "Guardfile",
     "LICENSE.txt",
     "README.md",
     "Rakefile",
-    "VERSION",
     "lib/marvel/client.rb",
     "lib/marvel/configuration.rb",
     "lib/marvel/connection.rb",
+    "lib/marvel/error.rb",
     "lib/marvel/request.rb",
+    "lib/marvel/response.rb",
+    "lib/marvel/version.rb",
     "lib/marvel_api.rb",
     "marvel_api.gemspec",
-    "spec/marvel_api/client_spec.rb",
+    "spec/fixtures/characters/character.json",
+    "spec/fixtures/characters/character_comics.json",
+    "spec/fixtures/characters/character_events.json",
+    "spec/fixtures/characters/character_series.json",
+    "spec/fixtures/characters/character_stories.json",
+    "spec/fixtures/characters/characters.json",
+    "spec/fixtures/comics/comic.json",
+    "spec/fixtures/comics/comic_characters.json",
+    "spec/fixtures/comics/comic_creators.json",
+    "spec/fixtures/comics/comic_events.json",
+    "spec/fixtures/comics/comic_stories.json",
+    "spec/fixtures/comics/comics.json",
+    "spec/fixtures/creators/creator.json",
+    "spec/fixtures/creators/creator_comics.json",
+    "spec/fixtures/creators/creator_events.json",
+    "spec/fixtures/creators/creator_series.json",
+    "spec/fixtures/creators/creator_stories.json",
+    "spec/fixtures/creators/creators.json",
+    "spec/fixtures/errors/empty_parameter.json",
+    "spec/fixtures/errors/excessive_filter_values.json",
+    "spec/fixtures/errors/invalid_credentials.json",
+    "spec/fixtures/errors/invalid_filter_value.json",
+    "spec/fixtures/errors/invalid_hash_ts_key_combo.json",
+    "spec/fixtures/errors/invalid_ordering.json",
+    "spec/fixtures/errors/invalid_parameter.json",
+    "spec/fixtures/errors/limit_invalid.json",
+    "spec/fixtures/errors/limit_over_100.json",
+    "spec/fixtures/errors/resource_not_found.json",
+    "spec/fixtures/events/event.json",
+    "spec/fixtures/events/event_characters.json",
+    "spec/fixtures/events/event_comics.json",
+    "spec/fixtures/events/event_creators.json",
+    "spec/fixtures/events/event_series.json",
+    "spec/fixtures/events/event_stories.json",
+    "spec/fixtures/events/events.json",
+    "spec/fixtures/series/serie.json",
+    "spec/fixtures/series/series.json",
+    "spec/fixtures/series/series_characters.json",
+    "spec/fixtures/series/series_comics.json",
+    "spec/fixtures/series/series_creators.json",
+    "spec/fixtures/series/series_events.json",
+    "spec/fixtures/series/series_stories.json",
+    "spec/fixtures/stories/stories.json",
+    "spec/fixtures/stories/story.json",
+    "spec/fixtures/stories/story_characters.json",
+    "spec/fixtures/stories/story_comics.json",
+    "spec/fixtures/stories/story_creators.json",
+    "spec/fixtures/stories/story_events.json",
+    "spec/fixtures/stories/story_series.json",
+    "spec/marvel_api/client/client_character_spec.rb",
+    "spec/marvel_api/client/client_comic_spec.rb",
+    "spec/marvel_api/client/client_creator_spec.rb",
+    "spec/marvel_api/client/client_event_spec.rb",
+    "spec/marvel_api/client/client_series_spec.rb",
+    "spec/marvel_api/client/client_story_spec.rb",
+    "spec/marvel_api/error_spec.rb",
     "spec/marvel_api_spec.rb",
     "spec/spec_helper.rb"
   ]
   s.homepage = "http://github.com/O-I/marvel"
   s.licenses = ["MIT"]
+  s.required_ruby_version = Gem::Requirement.new(">= 1.9.3")
   s.rubygems_version = "2.2.2"
   s.summary = "Ruby bindings for the Marvel API"
 
@@ -45,39 +105,36 @@ Gem::Specification.new do |s|
     s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<faraday>, [">= 0"])
-      s.add_runtime_dependency(%q<faraday_middleware>, [">= 0"])
-      s.add_runtime_dependency(%q<hashie>, [">= 0"])
+      s.add_runtime_dependency(%q<faraday>, ["< 0.10", ">= 0.7"])
+      s.add_runtime_dependency(%q<faraday_middleware>, ["< 0.10", ">= 0.8"])
+      s.add_runtime_dependency(%q<hashie>, [">= 0.4.0"])
       s.add_development_dependency(%q<pry>, [">= 0"])
       s.add_development_dependency(%q<rspec>, [">= 0"])
       s.add_development_dependency(%q<shoulda>, [">= 0"])
       s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_development_dependency(%q<bundler>, ["~> 1.0"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.8.7"])
-      s.add_development_dependency(%q<simplecov>, [">= 0"])
     else
-      s.add_dependency(%q<faraday>, [">= 0"])
-      s.add_dependency(%q<faraday_middleware>, [">= 0"])
-      s.add_dependency(%q<hashie>, [">= 0"])
+      s.add_dependency(%q<faraday>, ["< 0.10", ">= 0.7"])
+      s.add_dependency(%q<faraday_middleware>, ["< 0.10", ">= 0.8"])
+      s.add_dependency(%q<hashie>, [">= 0.4.0"])
       s.add_dependency(%q<pry>, [">= 0"])
       s.add_dependency(%q<rspec>, [">= 0"])
       s.add_dependency(%q<shoulda>, [">= 0"])
       s.add_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_dependency(%q<bundler>, ["~> 1.0"])
       s.add_dependency(%q<jeweler>, ["~> 1.8.7"])
-      s.add_dependency(%q<simplecov>, [">= 0"])
     end
   else
-    s.add_dependency(%q<faraday>, [">= 0"])
-    s.add_dependency(%q<faraday_middleware>, [">= 0"])
-    s.add_dependency(%q<hashie>, [">= 0"])
+    s.add_dependency(%q<faraday>, ["< 0.10", ">= 0.7"])
+    s.add_dependency(%q<faraday_middleware>, ["< 0.10", ">= 0.8"])
+    s.add_dependency(%q<hashie>, [">= 0.4.0"])
     s.add_dependency(%q<pry>, [">= 0"])
     s.add_dependency(%q<rspec>, [">= 0"])
     s.add_dependency(%q<shoulda>, [">= 0"])
     s.add_dependency(%q<rdoc>, ["~> 3.12"])
     s.add_dependency(%q<bundler>, ["~> 1.0"])
     s.add_dependency(%q<jeweler>, ["~> 1.8.7"])
-    s.add_dependency(%q<simplecov>, [">= 0"])
   end
 end