openlibrary 1.0.1 → 1.0.2

data/README.rdoc

@@ -1,9 +1,8 @@
-== Openlibrary 
+== Openlibrary 1.0.1 
 
+The openlibrary gem provides Ruby clients for the {Open Library REST API}[http://openlibrary.org/dev/docs/restful_api] and {Books API}[http://openlibrary.org/dev/docs/api/books].
 
-The openlibrary gem is a simple wrapper for the Open Library REST API.
-
-For more information on the REST calls, you can view the {Open Library API documentation}[http://openlibrary.org/dev/docs/restful_api]. For more info about Open Library development in general, visit the {Open Library Developer Center}[http://openlibrary.org/developers/api] and {Developer Notes}[http://openlibrary.org/dev].
+For more information about Open Library development, visit the {Open Library Developer Center}[http://openlibrary.org/developers/api] and {Developer Notes}[http://openlibrary.org/dev]. If you want to receive the latest updates and learn how to contribute, join us on the {ol-tech mailing list}[http://mail.archive.org/cgi-bin/mailman/listinfo/ol-tech]!
 
 
 == Installation
@@ -19,46 +18,146 @@ or in your Gemfile:
 
 == Usage
 
-You can retrieve a book's Open Library listing information.
+You can use the Books client to retrieve a book's Open Library listing information, and the REST client to make broader queries.
 
   # just require
   require 'openlibrary'
 
-Initiate your search 
+== REST Client 
 
-  # create a class proxy 
-  view = Openlibrary::View
-  
-  # lookup an item with the ISBN-10 or ISBN-13 
-  book_view = view.find_by_isbn("0451526538")
+You can use the REST client to look up books, authors, the revision history of any Open Library object, and recent changes to Open Library.
 
-or you can use the other built-in finder methods:
+=== Getting Started
 
-  find_by_lccn        # Library of congress catalog number
-  find_by_oclc        # Worldcat Control Number
-  find_by_olid        # Openlibrary ID
+Before anything else, create a new client: 
 
-Extract the book information:
-  
-  # have a look at the book's info URL on Openlibrary.org
-  book_view.info_url
+  client = Openlibrary::Client.new
+
+=== Books
+
+Since Open Library has varying amounts of information about the books in its database, and returns data in a schemaless format, not every book will have the same properties. Some common properties include `title`, `works`, and `contributors`, but most books will have more.
 
-  # or grab the URL of the book's thumbnail as shown on Openlibrary.org
-  book_view.thumbnail_url
+Find a book by its OLID:
 
-You can also retrieve a book's full metadata details.
+  book = client.book('olid')
   
-  # create a class proxy 
-  details = Openlibrary::Data
+  book.contributors     # array of book contributors
+  book.covers           # array of book cover ids
+  book.works            # array of works associated with the book
+  book.subjects         # array of subjects of the book
+
+  book.title            # book title
+  book.by_statement     # name of primary author(s) of the book
+  book.number_of_pages  # number of pages in the book
+  book.copyright_date   # book's copyright date
+  book.physical_format  # book's physical format
+  book.isbn_10[0]       # book's ISBN-10 identifier
+  book.isbn_13[0]       # book's ISBN-13 identifier
+  book.goodreads[0]     # book's goodreads id
+
+Get data on book contributors:
+
+  book.contributors.each do |c|
+    name = c.name   # contributor's name
+    role = c.role   # contributor's role (e.g., cover art)
+  end
+
+Get the book's subjects:
+
+  book.subjects.each do |s|
+    subject = s
+  end
+
+Get a book's Open Library object keys by its ISBN, LCCN, or OCLC identifier:
+
+  keys = client.book_by_isbn('isbn')   # isbn must be 10 or 13 characters long
+  keys = client.book_by_lccn('lccn')
+  keys = client.book_by_oclc('oclc')
+
+Iterate through the array of keys:
+
+  keys.each do |k|
+    key = k['key']  # keys are in the format '/books/{OLID}'
+  end
+
+Although keys are returned in an array, most arrays will only have one element.
+
+=== Authors
+
+Find an author by their OLID:
+
+  author = client.author('olid')
+
+  author.name                 # author name
+  author.birth_date           # author's birth date
+  author.death_date           # author's death date
+  author.last_modified.value  # date and time of last change to page
+  author.revision             # number of current revision
+  author.key!                 # author key, in the format '/authors/{OLID}
+
+=== Revision History
+
+Get the revision history of any Open Library object:
+
+  history = client.rev_history('key')
+
+The key should be in the format '/books/{OLID}', '/authors/{OLID}', '/works/{OLID}', etc.
+
+=== Recent Changes
+
+Get an array of recent changes to Open Library:
+
+  changes = client.recent
+
+== Books Client
+
+There are two classes in the openlibrary gem you can use to access the {Books API}[http://openlibrary.org/dev/docs/api/books]. Use Openlibrary::View to look up Open Library listing information, and Openlibrary::Data to get a book's full metadata details.
+
+=== Openlibrary::View
+
+Instantiate the class:
+
+  view = Openlibrary::View
+
+Look up a book by its ISBN-10 or ISBN-13:
+
+  book = view.find_by_isbn("0451526538")
+
+  book.info_url      # book's URL on Open Library
+  book.preview       # book's preview state, either 'noview' or 'full'
+  book.thumbnail_url # url of thumbnail cover of the book, if available
   
-  # lookup an item with the ISBN-10 or ISBN-13 
-  book_details = details.find_by_isbn("0451526538")
+  book.preview_url 
+  # Links to an archive.org page with a readable version of the book, 
+  # if one is available. If not, links to the book's Open Library 
+  # page. `book.preview` should be used first to test if a readable 
+  # preview of the book exists.
+
+Other built-in finder methods:
+
+  view.find_by_lccn   # Library of Congress catalog number
+  view.find_by_oclc   # Worldcat Control Number
+  view.find_by_olid   # Open Library ID
+
+
+=== Openlibrary::Data
+
+Instantiate the class:
+
+  data = Openlibrary::Data
+
+Look up a book by its ISBN-10 or ISBN-13:
+
+  book_details = data.find_by_isbn("0451526538")
   
-  # have a look at the book's title
-  book_details.title
+  book_details.title    # book's title
+  book_details.authors  # array of authors
+
+Other built-in finder methods:
 
-  # or an array of authors 
-  book_details.authors
+  view.find_by_lccn   # Library of Congress catalog number
+  view.find_by_oclc   # Worldcat Control Number
+  view.find_by_olid   # Open Library ID
 
 == CONTRIBUTORS
 

data/lib/openlibrary/client.rb

@@ -1,27 +1,28 @@
 require 'openlibrary/request'
 require 'openlibrary/client/books'
+require 'openlibrary/client/authors'
+require 'openlibrary/client/history'
+require 'openlibrary/client/recent'
+require 'openlibrary/client/editions'
 
 module Openlibrary
   class Client
     include Openlibrary::Request
     include Openlibrary::Books
-
-    attr_reader :username, :password
+    include Openlibrary::Authors
+    include Openlibrary::History
+    include Openlibrary::Recent
+    include Openlibrary::Editions
 
     # Initialize an Openlibrary::Client instance
     #
-    # options[:username]  - Username
-    # options[:password]  - Password
-    #
     def initialize(options={})
       unless options.kind_of?(Hash)
         raise ArgumentError, "Options hash required."
       end
 
-      # For future versions that include the ability to log in
-      # 
-      #  @username = options[:username] || Openlibrary.configuration[:username]
-      #  @password = options[:password] || Openlibrary.configuration[:password]
+      # For future versions, options may include cookie information 
+      # and alternative Accept headers (e.g., RDF instead of JSON)
     end
   end
 end

data/lib/openlibrary/client/authors.rb

@@ -0,0 +1,10 @@
+module Openlibrary
+  module Authors 
+    # Find authors in Open Library by their key 
+    #
+    def author(key)
+      data = request("/authors/#{key}")
+      Hashie::Mash.new(data)
+    end
+  end
+end

data/lib/openlibrary/client/books.rb

@@ -1,10 +1,31 @@
 module Openlibrary
   module Books
-    # Find books in Open Library by ISBN, OLID, LCCN, or OCLC
+    # Find books in Open Library by OLID, ISBN, LCCN, or OCLC
     #
     def book(olid)
       data = request("/books/#{olid}")
       Hashie::Mash.new(data)
     end
+
+    def book_by_isbn(isbn)
+      type = "/type/edition"
+      if isbn.length == 10
+        data = query("type=#{type}&isbn_10=#{isbn}")
+      elsif isbn.length == 13
+        data = query("type=#{type}&isbn_13=#{isbn}")
+      else
+        raise ArgumentError, "ISBN must be 10 or 13 characters."
+      end
+    end
+
+    def book_by_lccn(lccn)
+      type = "/type/edition"
+      data = query("type=#{type}&lccn=#{lccn}")
+    end
+
+    def book_by_oclc(oclc)
+      type = "/type/edition"
+      data = query("type=#{type}&oclc_numbers=#{oclc}")
+    end
   end
 end

data/lib/openlibrary/client/editions.rb

@@ -0,0 +1,10 @@
+module Openlibrary
+  module Editions
+    # Get the editions of a work
+    #
+    def editions(work, limit=10, offset=0)
+      data = request("/works/#{work}/editions.json?limit=#{limit}&offset=#{offset}")
+      editions = Hashie::Mash.new(data)
+    end
+  end
+end

data/lib/openlibrary/client/history.rb

@@ -0,0 +1,9 @@
+module Openlibrary
+  module History
+    # Get the revision history of an object in Open Library
+    #
+    def rev_history(object_key)
+      data = history("#{object_key}")
+    end
+  end
+end

data/lib/openlibrary/client/recent.rb

@@ -0,0 +1,9 @@
+module Openlibrary
+  module Recent
+    # Get an array of recent changes to Open Library
+    #
+    def recent
+      data = request("/recentchanges")
+    end
+  end
+end

data/lib/openlibrary/request.rb

@@ -15,11 +15,6 @@ module Openlibrary
     # path   - Request path
     #
     def request(path)
-      # This code is for future versions that allow user login.
-      # 
-      # username = username || Openlibrary.configuration[:username]
-      # password = password || Openlibrary.configuration[:password]
-
       url = "#{API_URL}#{path}"
 
       resp = RestClient.get(url, { accept: :json }) do |response, request, result, &block|
@@ -35,6 +30,46 @@ module Openlibrary
       parse(resp)
     end
 
+    # Get the history of an object in Open Library
+    # 
+    # object   - object key, e.g., '/books/OL1M'
+    #
+    def history(object)
+      url = "#{API_URL}#{object}.json?m=history"
+
+      resp = RestClient.get(url, { accept: :json }) do |response, request, result, &block|
+        case response.code
+        when 200
+          response.return!(request, result, &block)
+        when 401
+          raise Openlibrary::Unauthorized
+        when 404
+          raise Openlibrary::NotFound
+        end
+      end
+      parse(resp)
+    end
+
+    # Perform a query using the Query API
+    #
+    # path   - Request path
+    #
+    def query(query)
+      url = "#{API_URL}/query.json?#{query}"
+
+      resp = RestClient.get(url, { accept: :json }) do |response, request, result, &block|
+        case response.code
+        when 200
+          response.return!(request, result, &block)
+        when 401
+          raise Openlibrary::Unauthorized
+        when 404
+          raise Openlibrary::NotFound
+        end
+      end
+      parse(resp)
+    end
+
     def parse(resp)
       object = JSON.parse(resp.body)
       object

data/lib/openlibrary/version.rb

@@ -1,3 +1,3 @@
 module Openlibrary
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/openlibrary.gemspec

@@ -1,28 +1,28 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "openlibrary/version"
-
-Gem::Specification.new do |s|
-  s.name        = "openlibrary"
-  s.version     = Openlibrary::VERSION
-  s.authors     = ["Jay Fajardo"]
-  s.email       = ["jmrfajardo@gmail.com"]
-  s.homepage    = "http://www.proudcloud.net"
-  s.summary     = %q{Ruby Interface for the Openlibrary.org API}
-  s.description = %q{Openlibrary.org API Interface}
-
-  s.rubyforge_project = "openlibrary"
-
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
-
-  s.add_development_dependency 'rspec',   '~> 2.13'
-  s.add_development_dependency 'webmock', '~> 1.6'
-
-  s.add_runtime_dependency 'json',          '~> 1.7.7'
-  s.add_runtime_dependency 'rest-client',   '~> 1.6'
-  s.add_runtime_dependency 'hashie',        '~> 1.0'
-  s.add_runtime_dependency 'activesupport', '~> 3'
-end
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "openlibrary/version"
+
+Gem::Specification.new do |s|
+  s.name = "openlibrary"
+  s.version = Openlibrary::VERSION
+  s.authors = ["Jay Fajardo"]
+  s.email = ["jmrfajardo@gmail.com"]
+  s.homepage = "http://www.proudcloud.net"
+  s.summary = %q{Ruby Interface for the Openlibrary.org API}
+  s.description = %q{Openlibrary.org API Interface}
+
+  s.rubyforge_project = "openlibrary"
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rspec', '~> 2.13'
+  s.add_development_dependency 'webmock', '~> 1.6'
+
+  s.add_runtime_dependency 'json', '~> 1.7.7'
+  s.add_runtime_dependency 'rest-client', '~> 1.6'
+  s.add_runtime_dependency 'hashie', '~> 2.0.2'
+  s.add_runtime_dependency 'activesupport', '~> 3'
+end

data/spec/client_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 
 describe 'Client' do
-  let(:client)  { Openlibrary::Client.new() }
+  let(:client)  { Openlibrary::Client.new }
 
   describe '#new' do
     it 'requires an argument' do
@@ -26,15 +26,169 @@ describe 'Client' do
       book = client.book('OL23109860M')
 
       book.should be_a Hashie::Mash
-      book.contributors.should be_a        Array
-      book.covers.should be_a              Array
-
-      book.title.should eq                 'The Great Gatsby'
-      book.by_statement.should eq          'F. Scott Fitzgerald.'
-      book.number_of_pages.should eq       180
-      book.contributors[0].name.should eq  'Francis Cugat'
-      book.contributors[0].role.should eq  'Cover Art'
-      book.copyright_date.should eq        '1925'
+      book.contributors.should be_a Array
+      book.covers.should be_a       Array
+      book.works.should be_a        Array
+
+      book.title.should eq                    'The Great Gatsby'
+      book.by_statement.should eq             'F. Scott Fitzgerald.'
+      book.number_of_pages.should eq          180
+      book.contributors[0].name.should eq     'Francis Cugat'
+      book.contributors[0].role.should eq     'Cover Art'
+      book.copyright_date.should eq           '1925'
+      book.isbn_10[0].should eq               '0743273567'
+      book.identifiers.goodreads[0].should eq '4671'
+      book.identifiers.google[0].should eq    'iXn5U2IzVH0C'
+      book.physical_format.should eq          'Trade Paperback'
+      book.publishers[0].should eq            'Scribner'
+      book.subjects[1].should eq              'First loves -- Fiction'
+      book.subjects[0].should eq              'Traffic accidents -- Fiction'
+
+      # Because of a conflict with the internal `key?` method of 
+      # Hashie::Mash, any key actually named 'key' must be referenced 
+      # with a bang (!) to get the value.
+      book.key!.should eq                     '/books/OL23109860M'
+      book.languages[0].key!.should eq           '/languages/eng'
+    end
+  end
+
+  describe '#book_by_isbn' do
+    before do
+      isbn_10 = '046503912X'
+      type = '/type/edition'
+      stub_get("/query.json?type=#{type}&isbn_10=#{isbn_10}", 
+               'book_by_isbn.json')
+    end
+    it 'returns array of books' do
+      expect { client.book_by_isbn('046503912X').not_to raise_error }
+      expect { client.book_by_isbn('123').
+        to raise_error ArgumentError, "ISBN must be 10 or 13 characters." }
+
+      books = client.book_by_isbn('046503912X')
+
+      books.should be_a Array 
+      books[0].should be_a Hash
+
+      books[0]['key'].should eq '/books/OL6807502M'
+    end
+  end
+
+  describe '#book_by_lccn' do
+    before do
+      lccn = '00271772'
+      type = '/type/edition'
+      stub_get("/query.json?type=#{type}&lccn=#{lccn}",
+               'book_by_lccn.json')
+    end
+    it 'returns array of books' do
+      expect { client.book_by_lccn('00271772').not_to raise_error }
+
+      books = client.book_by_lccn('00271772')
+
+      books.should be_a Array
+      books[0].should be_a Hash
+    end
+  end
+
+  describe '#book_by_oclc' do
+    before do
+      oclc = '42860053'
+      type = '/type/edition'
+      stub_get("/query.json?type=#{type}&oclc_numbers=#{42860053}",
+               'book_by_oclc.json')
+    end
+    it 'returns array of books' do
+      expect { client.book_by_oclc('42860053').not_to raise_error }
+
+      books = client.book_by_oclc('42860053')
+
+      books.should be_a Array
+      books[0].should be_a Hash
+    end
+  end
+
+  describe '#author' do
+    before do
+      key = 'OL1A'
+      stub_get("/authors/#{key}", 'author.json')
+    end
+
+    it 'returns author details' do
+      expect { client.author('OL1A') }.not_to raise_error
+      
+      author = client.author('OL1A')
+
+      author.should be_a Hashie::Mash
+      author.name.should eq                'Sachi Rautroy'
+      author.personal_name.should eq       'Sachi Rautroy'
+      author.death_date.should eq          '2004'
+      author.birth_date.should eq          '1916'
+      author.last_modified.type.should eq  '/type/datetime'
+      author.last_modified.value.should eq '2008-11-16T07:25:54.131674'
+      author.id.should eq                  97
+      author.revision.should eq            6
+
+      # Because of a conflict with the internal `key?` method of 
+      # Hashie::Mash, any key actually named 'key' must be referenced 
+      # with a bang (!) to get the value.
+      author.key!.should eq                '/authors/OL1A'
+    end
+  end
+
+  describe '#rev_history' do
+    before do
+      key = '/books/OL1M'
+      stub_get("#{key}.json?m=history", 'history.json')
+    end
+
+    it 'returns the revision history of an object' do
+      expect { client.rev_history('/books/OL1M') }.not_to raise_error
+
+      history = client.rev_history('/books/OL1M')
+
+      history.should be_a Array
+      history[0].should be_a Hash
+    end
+  end
+
+  describe '#recent' do
+    before do
+      stub_get("/recentchanges", 'recent.json')
+    end
+
+    it 'returns recent changes to Open Library' do
+      expect { client.recent.not_to raise_error }
+
+      changes = client.recent
+
+      changes.should be_a Array
+      changes[0].should be_a Hash
+    end
+  end
+
+  describe '#editions' do
+    before do
+      work = 'OL27258W'
+      stub_get("/works/#{work}/editions.json?limit=10&offset=0", 'editions.json')
+    end
+
+    it 'returns the editions of a work' do
+      expect { client.editions('OL27258W') }.not_to raise_error
+
+      editions = client.editions('OL27258W', 10, 0)
+
+      editions.should be_a Hashie::Mash
+      editions.entries.should be_a Array
+
+      editions.size!.should eq      19
+      editions.links.next.should eq '/works/OL27258W/editions.json?limit=10&offset=10'
+      editions.links.self.should eq '/works/OL27258W/editions.json?limit=10&offset=0'
+      editions.links.work.should eq '/works/OL27258W'
+
+      # Failing tests for iteration through entries
+      #
+      # editions.entries[0].should be_a Hashie::Mash
+      # editions.entries[0].number_of_pages.should eq 322
     end
   end
 end