README.md

ShakenNotStirred

Ruby client for Cocktails API

Features • Setup • Usage • Implementation • Contribute

Features

• Providing developers with THE best dataset of cocktails & drinks from all over the world.
• Search through well known cocktails by name, description, ingredients, categories, timing, rating and more.
• Intuitive API interface navigation.
• URL generation process fully tested when applying filters for each request.
• API integration tests recorded and fully tested using VCR gem: fast tests (first HTTP request is real and it's response is stored for future runs), deterministic (tests will continue to pass, even if you are offline, or API goes down for maintenance) and accurate (responses will contain the same headers and body you get from a real request).

Setup

Install the gem by running:

gem install shaken_not_stirred

or add it to your Gemfile and run bundle install:

gem "shaken_not_stirred", "~> 0.0.7"

Usage

All Free, Basic, Advanced and Premium plans available here

Once completed this quick form the API Key will be sent to you by Juan Roldan (juanroldan1989@gmail.com)

Setup the API Key within an initializer:

# shaken_not_stirred_initializer.rb

ShakenNotStirred.configure do |config|
  config.api_key = "abcd1234"
end

Create a new filter instance like so:

filter = ShakenNotStirred.new

then call API methods, for instance:

Cocktails endpoint (Library vs. REST)

To fetch cocktails with ginger on its name:

filter.by_name("ginger")

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?name=ginger" -H "Authorization: Token token=your_api_key"

To fetch cocktails with amazing on its description:

filter.by_description("amazing")

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?description=amazing" -H "Authorization: Token token=your_api_key"

To fetch cocktails with rum on their ingredients:

filter.by_ingredients(["rum"])

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?ingredients[]=rum" -H "Authorization: Token token=your_api_key"

# cocktails with `rum` OR `gin` within their ingredients
$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?ingredients[]=rum,gin" -H "Authorization: Token token=your_api_key"

# cocktails with `tequila` AND `vodka` within their ingredients
$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?ingredients_only[]=tequila,vodka" -H "Authorization: Token token=your_api_key"

To fetch cocktails with classic on their categories:

filter.by_categories(["classic"])

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?categories[]=classic" -H "Authorization: Token token=your_api_key"

# cocktails with `drinks` OR `inventions` within their categories
$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?categories[]=drinks,inventions" -H "Authorization: Token token=your_api_key"

# cocktails with `inventions` AND `brandy` within their categories
$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?categories_only[]=inventions,brandy" -H "Authorization: Token token=your_api_key"

To fetch cocktails with dinner on their timing:

filter.by_timing("dinner")

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?timing=dinner" -H "Authorization: Token token=your_api_key"

To fetch cocktails that belong to the International Bartender Association:

filter.by_iba("true")
# OR
filter.by_iba(true)

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?iba=true" -H "Authorization: Token token=your_api_key"

To fetch cocktails that don't belong to the International Bartender Association:

filter.by_iba("false")
# OR
filter.by_iba(false)

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?iba=false" -H "Authorization: Token token=your_api_key"

To fetch cocktails that contain ice on many fields:

filter.by_multiple("ice")

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?multiple=ice" -H "Authorization: Token token=your_api_key"

PS: fields searched by are: name, description, ingredients, categories & timing.

To fetch cocktails randomnly:

# get a random cocktail on every request
filter.by_random
filter.by_random(1) # same behavior as `by_random`

# get 2 random cocktails on every request
filter.by_random(2)

# get N random cocktails on every request
filter.by_random(n)

# get a random cocktail on every request
$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?random=1" -H "Authorization: Token token=your_api_key"

# get 2 random cocktails on every request
$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?random=2" -H "Authorization: Token token=your_api_key"

# get N random cocktails on every request
$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?random=n" -H "Authorization: Token token=your_api_key"

All filters are chainable

To fetch cocktails that:

• contain classic on their categories AND
• belong to the International Bartender Association AND
• contain rum on their ingredients

filter = ShakenNotStirred.new

filter.by_categories(["classic"]).by_iba(true).by_ingredients(["rum"])

Once applied all the filters you need, make the API call to get the quotes:

filter.results

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?categories[]=classic&iba=true&ingredients[]=rum" -H "Authorization: Token token=your_api_key"

Categories endpoint

Cocktails API also provides an endpoint with all categories available to search by.

filter = ShakenNotStirred.new

filter.categories

filter.results

$ curl "http://api-cocktails.herokuapp.com/api/v1/categories" -H "Authorization: Token token=your_api_key"

Ingredients endpoint

Cocktails API also provides an endpoint with all ingredients available to search by.

filter = ShakenNotStirred.new

filter.ingredients

filter.results

$ curl "http://api-cocktails.herokuapp.com/api/v1/ingredients" -H "Authorization: Token token=your_api_key"

Pagination

Results returned per page: 20.

Pagination behavior is present in all 3 endpoints

Cocktails

filter = ShakenNotStirred.new

# fetch `cocktail` results from page `2`
filter.by_page(2)

filter.results

$ curl "http://api-cocktails.herokuapp.com/api/v1/cocktails?page=2" -H "Authorization: Token token=your_api_key"

Categories

filter = ShakenNotStirred.new

# fetch `category` results from page `4`
filter.categories.by_page(4)

filter.results

$ curl "http://api-cocktails.herokuapp.com/api/v1/categories?page=4" -H "Authorization: Token token=your_api_key"

Ingredients

filter = ShakenNotStirred.new

# fetch `ingredient` results from page `5`
filter.ingredients.by_page(5)

filter.results

$ curl "http://api-cocktails.herokuapp.com/api/v1/ingredients?page=5" -H "Authorization: Token token=your_api_key"

Implementation

Setting up this gem to work is really easy. Even more if you use has_scope gem:

class CocktailsController < ApplicationController

  has_scope :by_name,        as: :name
  has_scope :by_rating,      as: :rating
  has_scope :by_ingredients, as: :ingredients, type: :array
  has_scope :by_categories,  as: :categories, type: :array

  helper_method :collection

  def index
  end

  private

  def collection
    @collection ||= cocktails_filter.results
  end

  def cocktails_filter
    @cocktails_filter ||= apply_scopes(filter)
  end

  def filter
    @filter ||= ShakenNotStirred.new
  end
end

API Response

The response format is JSON by default. Results are provided as an array of objects with the following structure:

filter = ShakenNotStirred.new
filter.by_name("mojito")
filter.results
=> [
  {
    "id": 174,
    "name": "Mojito",
    "description": "Mojito (Spanish: [moˈxito]) is a traditional Cuban highball. Traditionally, a mojito is a cocktail that consists of five ingredients: white rum, sugar (traditionally sugar cane juice), lime juice, soda water, and mint. Its combination of sweetness, citrus, and herbaceous mint flavors is intended to complement the rum, and has made the mojito a popular summer drink.When preparing a mojito, fresh lime juice is added to sugar (or to simple syrup) and mint leaves. The mixture is then gently mashed with a muddler. The mint leaves should only be bruised to release the essential oils and should not be shredded. Then rum is added and the mixture is briefly stirred to dissolve the sugar and to lift the mint leaves up from the bottom for better presentation. Finally, the drink is topped with crushed ice and sparkling soda water. Mint leaves and lime wedges are used to garnish the glass.  The mojito is one of the most famous rum-based highballs. There are several versions of the mojito.",
    "ingredients": [
      "4 cl white rum",
      "3 cl fresh lime juice",
      "6 sprigs of Mentha|mint",
      "2 teaspoons sugar (or 2 cl of sugar syrup)"
    ],
    "categories": [
      "Cuban cocktails",
      "Cocktails with white rum",
      "Cold drinks",
      "Cuban alcoholic drinks",
      "Articles containing video clips",
      "Cuban inventions",
      "Cocktails with lime juice",
      "Cocktails with carbonated water",
      "Mint drinks",
      "Contemporary classics"
    ],
    "preparation": "Muddler|Muddle mint leaves with sugar and lime juice. Add a splash of soda water and fill the glass with cracked ice. Pour the rum and top with soda water. Garnish with sprig of mint leaves and lemon slice. Serve with straw.",
    "served": "On the rocks",
    "standard_drinkware": "collins",
    "standard_garnish": "lime & mint",
    "timing": "All day",
    "iba": true, # belongs to `International Bartenders Association`
    "rating": 9,
    "image_thumb_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTKsDEZWJhQTVBt5y9u-2gQgLXAB9EuUE6u5krAVZ9tmuCbQwnpOGTvwDtEoA&s",
    "image_large_url": "https://upload.wikimedia.org/wikipedia/commons/0/01/Mojito98775.jpeg",
    "video_url": "https://www.youtube.com/watch?v=_9v34KLET0g"
  }
...
]

Contribute

Got something interesting you'd like to add or change? Please feel free to Open a Pull Request

If you want to say thank you and/or support the active development of Shaken Not Stirred:

1. Add a GitHub Star to the project.
2. Tweet about the project on your Twitter.
3. Write a review or tutorial on Medium, Dev.to or personal blog.

Copyright

Copyright © 2024 Juan Roldan. See LICENSE.txt for further details.