shaken_not_stirred

KO | EN

gitlite — search

#javascript #typescript #android #ios #deep-learning #swift #cli #machine-learning #nodejs #docker #python #hacktoberfest

shaken_not_stirred

★ 47 Open GitHub ↗

:cocktail: :tropical_drink: Ruby client for Cocktails API

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ShakenNotStirred

Ruby client for [Cocktails API](https://cocktailsapi.xyz)

![https://github.com/juanroldan1989/shaken_not_stirred/commits/main](https://img.shields.io/github/last-commit/juanroldan1989/shaken_not_stirred.svg?style=flat-square&logo=github&logoColor=white)
![https://github.com/juanroldan1989/shaken_not_stirred/issues](https://img.shields.io/github/issues-raw/juanroldan1989/shaken_not_stirred.svg?style=flat-square&logo=github&logoColor=white)
[![Gem Version](https://badge.fury.io/rb/shaken_not_stirred.svg)](https://badge.fury.io/rb/shaken_not_stirred)
[![Code Climate](https://codeclimate.com/github/juanroldan1989/shaken_not_stirred/badges/gpa.svg)](https://codeclimate.com/github/juanroldan1989/shaken_not_stirred)
![Downloads](https://img.shields.io/gem/dv/shaken_not_stirred/0.0.7)
[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)

<p align="left">
  <a href="#features">Features</a> •
  <a href="#setup">Setup</a> •
  <a href="#usage">Usage</a> •
  <a href="#implementation">Implementation</a> •
  <a href="#contribute">Contribute</a>
</p>

# 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](https://github.com/vcr/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:

```ruby
gem install shaken_not_stirred
```

or add it to your Gemfile and run `bundle install`:

```ruby
gem "shaken_not_stirred", "~> 0.0.7"
```

# Usage

All `Free`, `Basic`, `Advanced` and `Premium` plans available [here](https://cocktailsapi.xyz)

Once completed this quick [form](https://docs.google.com/forms/d/12Ofvx3wg3fIwiS2u41JAv5CNtIExjenU7KVpqyIwMi8/viewform) the API Key will be sent to you by Juan Roldan (`juanroldan1989@gmail.com`)

Setup the API Key within an initializer:

```ruby
# shaken_not_stirred_initializer.rb

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

Create a new filter instance like so:

```ruby
filter = ShakenNotStirred.new
```

then call API methods, for instance:

## `Cocktails` endpoint (Library vs. REST)

To fetch cocktails with `ginger` on its name:

```ruby
filter.by_name("ginger")
```

```ruby
$ 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:

```ruby
filter.by_description("amazing")
```

```ruby
$ 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:

```ruby
filter.by_ingredients(["rum"])
```

```ruby
$ 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:

```ruby
filter.by_categories(["classic"])
```

```ruby
$ 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:

```ruby
filter.by_timing("dinner")
```

```ruby
$ 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`:

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

```ruby
$ 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`:

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

```ruby
$ 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:

```ruby
filter.by_multiple("ice")
```

```ruby
$ 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:

```ruby
# 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)
```

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

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

```ruby
filter.results
```

```ruby
$ 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.

```ruby
filter = ShakenNotStirred.new

filter.categories

filter.results
```

```ruby
$ 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.

```ruby
filter = ShakenNotStirred.new

filter.ingredients

filter.results
```

```ruby
$ 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

```ruby
filter = ShakenNotStirred.new

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

filter.results
```

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

### Categories

```ruby
filter = ShakenNotStirred.new

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

filter.results
```

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

### Ingredients

```ruby
filter = ShakenNotStirred.new

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

filter.results
```

```ruby
$ 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:

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

```ruby
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](https://github.com/juanroldan1989/shaken_not_stirred/pulls)

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

1. Add a [GitHub Star](https://github.com/juanroldan1989/shaken_not_stirred/stargazers) to the project.
2. Tweet about the project [on your Twitter](https://twitter.com/intent/tweet?text=Hey%20I've%20just%20discovered%20this%20cool%20app%20on%20Github%20by%20@JhonnyDaNiro%20-%20Deploy%20ECS%20Blueprint&url=https://github.com/juanroldan1989/shaken_not_stirred/&via=Github).
3. Write a review or tutorial on [Medium](https://medium.com), [Dev.to](https://dev.to) or personal blog.

# Copyright

shaken_not_stirred

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README