openlibrary 1.0.2 → 2.0.0

data/README.rdoc

@@ -1,4 +1,4 @@
-== Openlibrary 1.0.1 
+== Openlibrary 2.0.0
 
 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].
 
@@ -15,17 +15,18 @@ or in your Gemfile:
 
   gem 'openlibrary'
 
-
 == Usage
 
-You can use the Books client to retrieve a book's Open Library listing information, and the REST client to make broader queries.
+You can use the Books client to retrieve a book's Open Library listing information, and the REST client to perform more advanced queries and save changes to Open Library.
 
   # just require
   require 'openlibrary'
 
 == REST Client 
 
-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.
+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. 
+
+You can also use the REST client to log in and save changes to Open Library, after you register your profile (or your bot's profile) with the {API Usergroup}[http://openlibrary.org/usergroup/api]. Send a message to the {ol-tech mailing list}[http://mail.archive.org/cgi-bin/mailman/listinfo/ol-tech] to learn how!
 
 === Getting Started
 
@@ -35,7 +36,7 @@ Before anything else, create a new client:
 
 === 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.
+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. Common properties include `title`, `works`, and `contributors`, but most books will have more.
 
 Find a book by its OLID:
 
@@ -101,7 +102,7 @@ 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.
+The key should be in the format '/type/OLID'. E.g., '/books/OL9220552M', '/authors/OL27349A', or '/works/OL468516W'.
 
 === Recent Changes
 
@@ -109,6 +110,24 @@ Get an array of recent changes to Open Library:
 
   changes = client.recent
 
+=== Saving Changes
+
+Use the login method to get a session cookie:
+
+  cookie = client.login('username', 'password')
+
+Set the other parameters for the object you want to change:
+
+  key     = '/type/OLID'              # e.g., '/books/OL9220552M'
+  update  = full_object_with_changes  # must be JSON format
+  comment = 'changed X, Y, and Z'
+  
+Save your changes and receive the updated object as a response:
+
+  object = client.save(key, cookie, update, comment)
+
+NOTICE: Before you can actually save changes to Open Library, you need to register your profile (or bot) with the {API Usergroup}[http://openlibrary.org/usergroup/api]. Send a message to the {ol-tech mailing list}[http://mail.archive.org/cgi-bin/mailman/listinfo/ol-tech] to learn how!
+
 == 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.
@@ -162,8 +181,8 @@ Other built-in finder methods:
 == CONTRIBUTORS
 
 * Jay Fajardo https://github.com/jayfajardo
+* John Shutt https://github.com/pemulis
 * Robert Berry https://github.com/bdigital
 * Eric Larson https://github.com/ewlarson
 * Charles Horn https://github.com/hornc
-* John Shutt https://github.com/pemulis
 * Alex Grant https://github.com/grantovich

data/lib/openlibrary/client.rb

@@ -4,6 +4,8 @@ require 'openlibrary/client/authors'
 require 'openlibrary/client/history'
 require 'openlibrary/client/recent'
 require 'openlibrary/client/editions'
+require 'openlibrary/client/login'
+require 'openlibrary/client/save'
 
 module Openlibrary
   class Client
@@ -13,6 +15,8 @@ module Openlibrary
     include Openlibrary::History
     include Openlibrary::Recent
     include Openlibrary::Editions
+    include Openlibrary::Login
+    include Openlibrary::Save
 
     # Initialize an Openlibrary::Client instance
     #
@@ -20,9 +24,6 @@ module Openlibrary
       unless options.kind_of?(Hash)
         raise ArgumentError, "Options hash required."
       end
-
-      # 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/login.rb

@@ -0,0 +1,10 @@
+module Openlibrary
+  module Login
+    # Log in to Open Library
+    #
+    def login(username, password)
+      response = protected_login("#{username}", "#{password}")
+      cookie = Hashie::Mash.new(response).session
+    end
+  end
+end

data/lib/openlibrary/client/save.rb

@@ -0,0 +1,18 @@
+module Openlibrary
+  module Save
+    # Save changes to Open Library
+    # 
+    # key     - Open Library object key
+    # cookie  - Cookie retrieved by login method
+    # update  - Complete, updated Open Library JSON object
+    # comment - String comment describing the changes
+    #
+    # Note that 'update' can reference an external JSON file or 
+    # a properly formatted Ruby object.
+    #
+    def save(key, cookie, update, comment)
+      response = update("#{key}", "#{cookie}", "#{update}", "#{comment}")
+      Hashie::Mash.new(response)
+    end
+  end
+end

data/lib/openlibrary/request.rb

@@ -10,14 +10,15 @@ module Openlibrary
 
     protected
 
-    # Perform an API request
+    # Perform a GET request
     #
     # path   - Request path
     #
-    def request(path)
+    def request(path, params={})
+      params.merge!(accept: :json)
       url = "#{API_URL}#{path}"
 
-      resp = RestClient.get(url, { accept: :json }) do |response, request, result, &block|
+      resp = RestClient.get(url, params) do |response, request, result, &block|
         case response.code
         when 200
           response.return!(request, result, &block)
@@ -30,14 +31,16 @@ module Openlibrary
       parse(resp)
     end
 
+
     # Get the history of an object in Open Library
     # 
-    # object   - object key, e.g., '/books/OL1M'
+    # object   - Object key, e.g., '/books/OL1M'
     #
-    def history(object)
+    def history(object, params={})
+      params.merge!(accept: :json)
       url = "#{API_URL}#{object}.json?m=history"
 
-      resp = RestClient.get(url, { accept: :json }) do |response, request, result, &block|
+      resp = RestClient.get(url, params) do |response, request, result, &block|
         case response.code
         when 200
           response.return!(request, result, &block)
@@ -52,12 +55,62 @@ module Openlibrary
 
     # Perform a query using the Query API
     #
-    # path   - Request path
+    # query - Query path, e.g. "type=/type/edition&isbn_10=XXXXXXXXXX"
     #
-    def query(query)
+    def query(query, params={})
+      params.merge!(accept: :json)
       url = "#{API_URL}/query.json?#{query}"
 
-      resp = RestClient.get(url, { accept: :json }) do |response, request, result, &block|
+      resp = RestClient.get(url, params) 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 protected_login(username, password, params={})
+      params.merge!(content_type: :json, accept: :json)
+      url = "#{API_URL}/account/login"
+      login = { 'username' => username, 'password' => password }.to_json
+
+      resp = RestClient.post(url, login, params) do |response|
+        case response.code
+        when 200
+          session = response.cookies
+          session
+        when 401
+          raise Openlibrary::Unauthorized
+        when 404
+          raise Openlibrary::NotFound
+        end
+      end
+    end
+
+    # Update an Open Library object 
+    #
+    # key     - Object key the Open Library resource
+    # cookie  - Cookie retrieved by the login method
+    # update  - Complete updated Open Library object in JSON format
+    # comment - Comment describing the change(s) to the object
+    #
+    def update(key, cookie, update, comment, params={})
+      cookie_header = { 'Cookie' => cookie }
+      comment_header = { 
+        'Opt' => '"http://openlibrary.org/dev/docs/api"; ns=42',
+        '42-comment' => comment 
+      }
+      params.merge!(cookie_header)
+      params.merge!(comment_header)
+      params.merge!(content_type: :json, accept: :json)
+      url = "#{API_URL}#{key}"
+
+      resp = RestClient.put(url, update, params) do |response, request, result, &block|
         case response.code
         when 200
           response.return!(request, result, &block)

data/lib/openlibrary/version.rb

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

data/openlibrary.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_development_dependency 'rspec', '~> 2.13'
-  s.add_development_dependency 'webmock', '~> 1.6'
+  s.add_development_dependency 'webmock', '~> 1.11'
 
   s.add_runtime_dependency 'json', '~> 1.7.7'
   s.add_runtime_dependency 'rest-client', '~> 1.6'

data/spec/client_spec.rb

@@ -191,4 +191,41 @@ describe 'Client' do
       # editions.entries[0].number_of_pages.should eq 322
     end
   end
+
+  describe '#login' do
+    before do
+      stub_http_request(:post, "www.openlibrary.org/account/login").
+        with( body: "{\"username\":\"username\",\"password\":\"password\"}" ).
+        to_return( status: 200, headers: {'Set-Cookie' => 'session=cookie'} )
+    end
+
+    it 'logs in to Open Library' do
+      expect { client.login('username', 'password') }.not_to raise_error
+
+      cookie = client.login('username', 'password')
+      cookie.should eq "cookie"
+    end
+  end
+
+  describe '#after_save' do
+    before do
+      key = "/books/OL9674499M"
+      comment = 'update weight and number of pages'
+      stub_put(key, 'save_after_change.json', comment)
+    end
+
+    it 'PUTs the updated object, and receives the updated object as a response' do
+      key = "/books/OL9674499M"
+      cookie = 'cookie'
+      update = fixture('save_after_change.json')
+      comment = 'update weight and number of pages'
+
+      expect { client.save(key, cookie, update, comment) }.not_to raise_error
+
+      object = client.save(key, cookie, update, comment)
+
+      object.weight.should eq '1.5 pounds'
+      object.number_of_pages.should eq 1103
+    end
+  end
 end

data/spec/fixtures/save_after_change.json

@@ -0,0 +1,42 @@
+{ "authors" : [ { "key" : "/authors/OL448939A" } ],
+  "covers" : [ 187816 ],
+  "created" : { "type" : "/type/datetime",
+      "value" : "2008-04-30T09:38:13.731961"
+    },
+  "edition_name" : "10 Anv edition",
+  "first_sentence" : { "type" : "/type/text",
+      "value" : "I am seated in an office, surrounded by heads and bodies."
+    },
+  "ia_box_id" : [ "IA138916" ],
+  "identifiers" : { "goodreads" : [ "75786" ],
+      "librarything" : [ "903" ]
+    },
+  "isbn_10" : [ "0316066524" ],
+  "isbn_13" : [ "9780316066525" ],
+  "key" : "/books/OL9674499M",
+  "languages" : [ { "key" : "/languages/eng" } ],
+  "last_modified" : { "type" : "/type/datetime",
+      "value" : "2012-02-19T03:27:30.858827"
+    },
+  "latest_revision" : 8,
+  "number_of_pages" : 1103,
+  "ocaid" : "infinitejestnove00wall",
+  "physical_dimensions" : "8.9 x 5.9 x 1.8 inches",
+  "physical_format" : "Paperback",
+  "publish_date" : "November 13, 2006",
+  "publishers" : [ "Back Bay Books" ],
+  "revision" : 8,
+  "source_records" : [ "ia:infinitejestnove00wall" ],
+  "subjects" : [ "Popular American Fiction",
+      "Fiction",
+      "Fiction - General",
+      "General",
+      "Fiction / General",
+      "Addicts",
+      "Compulsive behavior"
+    ],
+  "title" : "Infinite Jest",
+  "type" : { "key" : "/type/edition" },
+  "weight" : "1.5 pounds",
+  "works" : [ { "key" : "/works/OL2943602W" } ]
+}

data/spec/fixtures/save_before_change.json

@@ -0,0 +1,42 @@
+{ "authors" : [ { "key" : "/authors/OL448939A" } ],
+  "covers" : [ 187816 ],
+  "created" : { "type" : "/type/datetime",
+      "value" : "2008-04-30T09:38:13.731961"
+    },
+  "edition_name" : "10 Anv edition",
+  "first_sentence" : { "type" : "/type/text",
+      "value" : "I am seated in an office, surrounded by heads and bodies."
+    },
+  "ia_box_id" : [ "IA138916" ],
+  "identifiers" : { "goodreads" : [ "75786" ],
+      "librarything" : [ "903" ]
+    },
+  "isbn_10" : [ "0316066524" ],
+  "isbn_13" : [ "9780316066525" ],
+  "key" : "/books/OL9674499M",
+  "languages" : [ { "key" : "/languages/eng" } ],
+  "last_modified" : { "type" : "/type/datetime",
+      "value" : "2012-02-19T03:27:30.858827"
+    },
+  "latest_revision" : 8,
+  "number_of_pages" : 1104,
+  "ocaid" : "infinitejestnove00wall",
+  "physical_dimensions" : "8.9 x 5.9 x 1.8 inches",
+  "physical_format" : "Paperback",
+  "publish_date" : "November 13, 2006",
+  "publishers" : [ "Back Bay Books" ],
+  "revision" : 8,
+  "source_records" : [ "ia:infinitejestnove00wall" ],
+  "subjects" : [ "Popular American Fiction",
+      "Fiction",
+      "Fiction - General",
+      "General",
+      "Fiction / General",
+      "Addicts",
+      "Compulsive behavior"
+    ],
+  "title" : "Infinite Jest",
+  "type" : { "key" : "/type/edition" },
+  "weight" : "1.4 pounds",
+  "works" : [ { "key" : "/works/OL2943602W" } ]
+}

data/spec/spec_helper.rb

@@ -13,11 +13,32 @@ end
 
 def stub_get(path, fixture_name)
   stub_request(:get, api_url(path)).
-    with(:headers => {'Accept'=>'application/json'}).
+    with(headers: {
+      'Accept'=>'application/json'
+    }).
     to_return(
-      :status => 200, 
-      :body => fixture(fixture_name), 
-      :headers => {}
+      status:  200, 
+      body:    fixture(fixture_name), 
+      headers: {}
+    )
+end
+
+def stub_put(path, fixture_name, comment)
+  stub_request(:put, api_url(path)).
+    with(
+      body: fixture(fixture_name),
+      headers: {
+        'Accept'       => 'application/json',
+        'Content-Type' => 'application/json',
+        'Opt'          => '"http://openlibrary.org/dev/docs/api"; ns=42',
+        '42-comment'   => comment,
+        'Cookie'       => 'cookie',
+        'User-Agent'   => 'Ruby'
+      }).
+    to_return(
+      status:  200,
+      body:    fixture(fixture_name),
+      headers: {}
     )
 end
 

metadata

@@ -1,93 +1,119 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: openlibrary
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 2.0.0
   prerelease: 
-  version: 1.0.2
 platform: ruby
-authors: 
+authors:
 - Jay Fajardo
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2013-03-05 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2013-04-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "2.13"
+      - !ruby/object:Gem::Version
+        version: '2.13'
   type: :development
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: webmock
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "1.6"
+      - !ruby/object:Gem::Version
+        version: '2.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.11'
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: json
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
         version: 1.7.7
   type: :runtime
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: rest-client
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.7
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "1.6"
+      - !ruby/object:Gem::Version
+        version: '1.6'
   type: :runtime
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: hashie
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
         version: 2.0.2
   type: :runtime
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: activesupport
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "3"
+      - !ruby/object:Gem::Version
+        version: 2.0.2
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
-  version_requirements: *id006
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
 description: Openlibrary.org API Interface
-email: 
+email:
 - jmrfajardo@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - README.rdoc
@@ -98,7 +124,9 @@ files:
 - lib/openlibrary/client/books.rb
 - lib/openlibrary/client/editions.rb
 - lib/openlibrary/client/history.rb
+- lib/openlibrary/client/login.rb
 - lib/openlibrary/client/recent.rb
+- lib/openlibrary/client/save.rb
 - lib/openlibrary/data.rb
 - lib/openlibrary/details.rb
 - lib/openlibrary/errors.rb
@@ -115,36 +143,35 @@ files:
 - spec/fixtures/editions.json
 - spec/fixtures/history.json
 - spec/fixtures/recent.json
+- spec/fixtures/save_after_change.json
+- spec/fixtures/save_before_change.json
 - spec/openlibrary_spec.rb
 - spec/spec_helper.rb
 homepage: http://www.proudcloud.net
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: openlibrary
-rubygems_version: 1.8.22
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Ruby Interface for the Openlibrary.org API
-test_files: 
+test_files:
 - spec/client_spec.rb
 - spec/fixtures/author.json
 - spec/fixtures/book.json
@@ -154,5 +181,7 @@ test_files:
 - spec/fixtures/editions.json
 - spec/fixtures/history.json
 - spec/fixtures/recent.json
+- spec/fixtures/save_after_change.json
+- spec/fixtures/save_before_change.json
 - spec/openlibrary_spec.rb
 - spec/spec_helper.rb