English
资源说明：Google Books API volume search
= Bookle
Query Google Books[http://code.google.com/apis/books/] API[http://code.google.com/apis/books/docs/v1/using.html].
= How to use it
Require the gem:
require 'bookle'
Get an API object:
api = Bookle.api('my Google Books API key')
Set one or more searchable fields to a value:
api.subject = 'flowers'
Running the search:
api.search
= Details
The Google API will return a set of result that is available through the API's instance variable volumes as an array.
The original intent of this gem was to search by ISBN. To that effect a convenience instance variable has been created called volume that contains a volume/book object when there is only one volume returned by the Google API.
The Google API returns a hash of hashes and a similar structure is generated by Bookle but at an object level (objects containing other objects) to make access to the information easier. This structure, however, is not ideal when instantiating book objects or mass assigning values to them. In order to simplify the process at that level I created a gem called hasherizer[https://rubygems.org/gems/hasherizer]. This gem will recursively look inside of an object to extract all instance variables to a one level flat hash. Thanks to this gem the volume/book objects returned by Bookle have been endowed with the method #hash with use hasherizer to generate a hash that can be used to instantiate book objects and/or assign values to them (e.g.: book = Book.new(api.volume.hash)).
= Warnings
If the instance variable volume is empty it could mean that either the search was unsuccessful or that Google's API returned more than one result, which could happen even when searching by ISBN. This situation was encountered during testing and in one occasion the ISBN values of the returned volumes didn't even match.
There is also a problem with the number of total volumes the Google API reports back. Running the same query repeated times yields different number of total volumes. This was very apparent while paginating through the results (repetead searches with offset values). Take this into consideration while working with the returned results and do not base your logic on the number of volumes the API says it has, it very likely will not be accurate, in my experience.
= CACERT (Certification Authority CERTificates)
"There is a long standing issue in Ruby where the net/http library by default does not check the validity of an SSL certificate during a TLS handshake...". Please read this gist[https://gist.github.com/867550] for more information and keep reading here after you're finished.
What all that means is that a file with the SSL certificates must exist in your system in order to use the Google Books API (through Bookle). Bookle ships with a file that contains those certificates and provides a way for updating them. If you ever get an error similar to this:
OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed
it might mean that your copy of the file containing the SSL certificates is too old. If that is the case you can update the file version by getting into an irb session, getting an API object and calling the method #update_cacert_file on it.
= TODO
1) Exception support for lack of connectivity, etc.
2) Write tests.
3) Automate the cacert file update process.
4) Updae cacert file during installation in addition to shipping file with gem.
== Contact Info
I can be contacted at mailto:pepe.hipolito@gmail.com
== Contributing to Bookle
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
* Fork the project.
* Start a feature/bugfix branch.
* Commit and push until you are happy with your contribution.
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
== Copyright
Copyright (c) 2012 Pepe Hipolito. MIT license. See LICENSE.txt for further details.
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
