tylerhunt / brewery_db

A Ruby library for using the BreweryDB API.

BreweryDB

A Ruby library for using the BreweryDB API.

Requirements

Tested and known to work with the following Rubies:

• Ruby/MRI 1.9.2, 1.9.3, 2.0.0, 2.1
• JRuby 1.7.x in 1.9 mode
• Rubinius ~> 2.2

Installation

Add this line to your application’s Gemfile:

gem 'brewery_db'

And then execute:

$ bundle

Or install it yourself as:

$ gem install brewery_db

Configuration

You must have a valid API key to use the BreweryDB API. If you don’t yet have one, you may request one here.

You can use the following method to configure your API key:

brewery_db = BreweryDB::Client.new do |config|
  config.api_key = API_KEY
end

Logging

Optionally, you can configure BreweryDB to use a logger for to help with request debugging.

brewery_db = BreweryDB::Client.new do |config|
  # ...
  config.logger = Rails.logger
end

Usage

Once an API key has been set, resources can be called on the client instance.

brewery_db.beers.all(abv: '5.5')
brewery_db.beers.find('vYlBZQ')
brewery_db.beers.random

brewery_db.breweries.all(established: 2006)
brewery_db.breweries.find('d1zSa7')

brewery_db.brewery('d1zSa7').beers

brewery_db.categories.all
brewery_db.categories.find(1)

brewery_db.fermentables.all(country: 'Brazil')
brewery_db.fermentables.find(1924)

brewery_db.fluid_size.all
brewery_db.fluid_size.find(1)

brewery_db.glassware.all
brewery_db.glassware.find(1)

brewery_db.hops.all
brewery_db.hops.find(1)

brewery_db.search.all(q: 'IPA')
brewery_db.search.beers(q: 'IPA')
brewery_db.search.breweries(q: 'IPA')
brewery_db.search.guilds(q: 'IPA')
brewery_db.search.events(q: 'IPA')
brewery_db.search.upc(code: '030613000043')

brewery_db.styles.all
brewery_db.styles.find(1)

brewery_db.locations.all(locality: 'San Francisco')

brewery_db.yeasts.all
brewery_db.yeasts.find(1836)

brewery_db.menu.beer_availability

WebHooks

The BreweryDB API also provides webhooks, which can be used to:

keep your local data stores in sync with the main BreweryDB API. Instead of having to constantly query the API, webhooks will send you a message when something changes.

This library provides a simple abstraction over the data posted by those webhooks.

webhook = BreweryDB::WebHook.new(webhook_params_hash)

Validating a WebHook

The webhook_params_hash should contain the key, nonce, action, etc. sent as the payload of the webhook. A BreweryDB::WebHook object can validate the posted data by SHA-1 hashing your API key with the nonce value and comparing it to the key value (as per the docs).

webhook.valid?(API_KEY) # => true or false

Idiomatic Access to WebHook Parameters

The BreweryDB::WebHook object also provides an idiomatic Ruby interface to the parameters. For example, one of the parameters posted in a webhook is attributeId, which is the BreweryDB ID for a brewery, beer, etc. This parameter is exposed by an instance of BreweryDB::WebHook as #attribute_id.

Here’s the full list of parameters:

webhook.action #=> 'insert'
webhook.attribute #=> 'beer'
webhook.attribute_id #=> 'x6bRxw'
webhook.key #=> 'some-long-key-value-here'
webhook.nonce #=> 'some-long-nonce-value-here'
webhook.sub_action #=> 'brewery-insert'
webhook.sub_attribute_id #=> 'q6vJUK'
webhook.timestamp #=> '1350573527'

Examples

Additional examples may be found in the examples directory.

Contributing

1. Fork it.
2. Create your feature branch (git checkout -b my-new-feature).
3. Commit your changes (git commit -am 'Added some feature').
4. Push to the branch (git push origin my-new-feature).
5. Create a new Pull Request.

Contributors

Thanks to the following people who have contributed patches or helpful suggestions:

• Steven Harman
• Jésus Lopes
• Matt Griffin

Copyright

Copyright © 2012 Tyler Hunt. See LICENSE for details.

brewery_db's Issues

respond_to? not passing private method flag

From the current, main brewery_db.rb:

def respond_to?(method, include_private=false)
  client.respond_to?(method) || super
end

The include_private flag should likely be passed to the client.respond_to? call, as well.

Create beer/brewery

Can you please add possibility to add beers and breweries?

POST: /beers
POST: /breweries

Thanks

License missing from gemspec

RubyGems.org doesn't report a license for your gem. This is because it is not specified in the gemspec of your last release.

via e.g.

spec.license = 'MIT'
# or
spec.licenses = ['MIT', 'GPL-2']

Including a license in your gemspec is an easy way for rubygems.org and other tools to check how your gem is licensed. As you can image, scanning your repository for a LICENSE file or parsing the README, and then attempting to identify the license or licenses is much more difficult and more error prone. So, even for projects that already specify a license, including a license in your gemspec is a good practice. See, for example, how rubygems.org uses the gemspec to display the rails gem license.

There is even a License Finder gem to help companies/individuals ensure all gems they use meet their licensing needs. This tool depends on license information being available in the gemspec. This is an important enough issue that even Bundler now generates gems with a default 'MIT' license.

I hope you'll consider specifying a license in your gemspec. If not, please just close the issue with a nice message. In either case, I'll follow up. Thanks for your time!

Appendix:

If you need help choosing a license (sorry, I haven't checked your readme or looked for a license file), GitHub has created a license picker tool. Code without a license specified defaults to 'All rights reserved'-- denying others all rights to use of the code.
Here's a list of the license names I've found and their frequencies

p.s. In case you're wondering how I found you and why I made this issue, it's because I'm collecting stats on gems (I was originally looking for download data) and decided to collect license metadata,too, and make issues for gemspecs not specifying a license as a public service :). See the previous link or my blog post aobut this project for more information.

Faraday requirements should move to Resource

From the current client.rb:

require 'faraday'
require 'faraday_middleware'

These lines should probably move over to the resource.rb file, now that the connection has been extracted out.

`#all` isn't really ALL.

I wonder if #all really should be fetching all of the resource, not just the first page. I know you can specify the page, but I really want a way to iterate through all of a thing. Maybe each resource also needs an .each which will yield out each individual resource but keep pulling pages.

module Breweries
  PAGE_SIZE = 50
  # ...

  def each(params={}, &block)
    page = 1
    breweries = all(params)

    while breweries.any?
      breweries.each do { |b| block.call(b) }
      return if breweries.size < PAGE_SIZE

      breweries = all(params.merge(p: page))
    end
  end

  #...
end

Of course this wouldn't be duplicated across all resources. Instead I could image a #get_in_batches method that did the fetching and just yielded the whole array of results, but you get the idea.

Thoughts?

Beer -> Random

How can I get random beer with that gem?

http://www.brewerydb.com/developers/docs-endpoint/beer_random

Behavior of paginated collection prevents pagination

Given something like beers = db.search.beers(q: 'Ale') the usual thing I'd want to do is iterate over the result and render a page of data, then wait and see if the user wants more.

There doesn't appear to be a simple way to iterate over just the returned page without loading all of the pages. This is really surprising behavior to me.

I'm cheating my way back to the unpaginated collection with beers.instance_eval { @collection }.each ...

Am I missing something obvious? If not, are you open to adding an option to not return a paginated collection from API calls?

Release new gem

The readme is inconsistent with the code (initialize with block works in master, but not in released version) if you just do gem 'brewery_db'.

I'm just going to lock to the repo, but it would be sweet to get a new version released. Thanks!