Bol

A Ruby wrapper around the bol.com developers API, that will be made available as a Gem. Currently in beta stage.

Getting started

Installation

Bol is a simple Ruby gem, so it requires a working installation of Ruby with Ruby gems. Note: Ruby 1.9 is required. Install the gem:

$ gem install bol

Or, if your project uses Bundler simply add it to your Gemfile:

gem 'bol'

Then, simply require it in your code, provide some configuration settings and query away.

Configuration

To be allowed to make requests to the Bol.com API you need to register on their site and request a access key and secret. Configure the Bol gem as follows:

Bol.configure do |c|
  c.access_key = 'your public access key'
  c.secret = 'your private secret'
  c.per_page = 10
end

Example application

See an example Sinatra application implementing basic search-and-display functionality: https://gist.github.com/1724664. There's an introductory blog post to go with it.

Available operations

Here are the currently working operations:

Loading a specific product

If you know an ID, you can load a product directly:

product = Bol::Product.find(params[:id])
product.title
product.cover(:medium)
product.referral_url('my_associate_id')

Listing products

You can get a list of popular or bestselling products:

• Bol.top_products
• Bol.top_products_overall
• Bol.top_products_last_week
• Bol.top_products_last_two_months
• Bol.new_products
• Bol.preorder_products

Or, you can apply a scope to limit results to a category:

Bol::Scope.new(params[:category_id]).top_producs

Searching products

You can search globally for keywords or ISBN and use a Arel-like syntax for setting options:

Bol.search(params[:query]).limit(10).offset(10).order('sales_ranking ASC')
Bol.search(params[:query]).page(params[:page])

You can scope your search to a specific category:

Bol::Scope.new(params[:category_id]).search(params[:query])

Loading categories and refinements

Loading all top-level categories (e.g. DVDs or English Book) is simple enough:

categories = Bol.categories
categories.first.name # => 'Books'

You can load subsequent subcategories:

Bol::Scope.new(categories.first.id).categories

Refinements (e.g. 'under 10 euros') work much the same way as categories, but are grouped under a shared name, such as group 'Price' with refinements 'up to 10 euros', '10 to 20 euros', etc.:

groups = Bol.refinements
group = groups.first
group.name # => 'Price'
group.refinements.first.name # => 'under 10 euros'

Scoping operations

The Bol::Scope object limits results to given categories and/or refinements. You can create a scope using explicit IDs, and you can do basic combinations:

books = Bol::Scope.new(some_category_id)
cheap = Bol::Scope.new(some_refinement_id)
(books + cheap).top_products

Here's an overview of all the operations that should still be implemented:

Background

The available operations map almost directly to operations provided by the API to search, load lists of products or load a single product by ID. I do aim to a add a little sugar to make working with Ruby objects a little easier:

• Add page helper method to combine limit and offset
• Scope operations by category in a ActiveRecord association style
• Delay API calls until explicitly requested or triggered by looping over results

Wishlist

• Allow scoping by category or refinement objects instead of just IDs
• Add a simple identiy map, so the same product does not have to be loaded twice when requested twice
• Properly differentiate between product types. Currently built around books; DVDs, music and toys may or may not work as expected.
• Add default ordering of products

I do not need this stuff myself, but I will gladly take pull requests for such features.

Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

History

For a full list of changes, please see CHANGELOG.md

License

Copyright (C) 2011 by Arjan van der Gaag. Published under the MIT license. See LICENSE.md for details.