A simple Ruby wrapper around the bol.com developer API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


# Bol

[![Build Status](https://secure.travis-ci.org/avdgaag/bol.png?branch=master)](http://travis-ci.org/avdgaag/bol)

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

[docs]: http://developers.bol.com

## 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`:

[Bundler]: http://gembundler.com

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

### Example application

See an example Sinatra application implementing basic search-and-display 
functionality: [https://gist.github.com/1724664](https://gist.github.com/1724664).
There's [an introductory blog post](http://arjanvandergaag.nl/blog/bol-gem.html)
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])

### 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:


### 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')

You can scope your search to a specific category:


### Loading categories and refinements

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

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

You can load subsequent subcategories:


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

## 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

## 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
* 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.