From f5a6aa8f21d4e977b750f997f03cb12ac126e4f3 Mon Sep 17 00:00:00 2001 From: Juan Roldan Date: Thu, 11 Jun 2020 22:48:40 -0300 Subject: [PATCH] README updated - Cocktails API docs adjusted with REST examples - License file updated accordingly. --- LICENSE.txt | 2 +- README.md | 126 ++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 108 insertions(+), 20 deletions(-) diff --git a/LICENSE.txt b/LICENSE.txt index dd8d469..6b3251b 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,4 @@ -Copyright (c) 2020 Juan Roldan +Copyright (c) 2023 Juan Roldan Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/README.md b/README.md index 6487560..f4ab42d 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,26 @@ -
- shaken_not_stirred ruby logo -
+ # ShakenNotStirred + [![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](http://ruby-gem-downloads-badge.herokuapp.com/shaken_not_stirred/0.0.7?type=total&color=brightgreen)](https://rubygems.org/gems/shaken_not_stirred) [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT) + -Ruby client for [Cocktails API](https://juanroldan.com.ar/cocktails-api-landing) +Ruby client for [Cocktails API](https://cocktailsapi.xyz) ## 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). +- 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). ## Installation @@ -38,7 +38,7 @@ gem "shaken_not_stirred", "~> 0.0.7" ## 1. Usage -All `Free`, `Basic`, `Advanced` and `Premium` plans available [here](https://juanroldan.com.ar/cocktails-api-landing) +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`) @@ -60,8 +60,7 @@ filter = ShakenNotStirred.new then call API methods, for instance: - -### `Cocktails` endpoint +### `Cocktails` endpoint (Library vs. REST) To fetch cocktails with `ginger` on its name: @@ -69,52 +68,98 @@ To fetch cocktails with `ginger` on its name: 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") +``` -# fields included are: `name`, `description`, `ingredients`, `categories` & `timing` +```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 @@ -129,6 +174,17 @@ filter.by_random(2) 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: @@ -141,8 +197,6 @@ To fetch cocktails that: filter = ShakenNotStirred.new filter.by_categories(["classic"]).by_iba(true).by_ingredients(["rum"]) - -filter.results ``` Once applied all the filters you need, make the API call to get the quotes: @@ -151,6 +205,10 @@ Once applied all the filters you need, make the API call to get the quotes: 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. @@ -163,6 +221,10 @@ 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. @@ -175,9 +237,17 @@ filter.ingredients filter.results ``` +```ruby +$ curl "http://api-cocktails.herokuapp.com/api/v1/ingredients" -H "Authorization: Token token=your_api_key" +``` + ### Pagination -Pagination behavior is present in all 3 endpoints: `cocktails`, `categories` and `ingredients`. +Results returned per page: 20. + +Pagination behavior is present in all 3 endpoints + +#### Cocktails ```ruby filter = ShakenNotStirred.new @@ -188,6 +258,12 @@ 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 @@ -197,6 +273,12 @@ 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 @@ -206,7 +288,12 @@ 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" +``` + ## 2. Implementation + Setting up this gem to work is really easy. Even more if you use `has_scope` gem: ```ruby @@ -239,10 +326,11 @@ end ``` ## 3. Response + The response format is JSON by default. Results are provided as an array of objects with the following structure:
- shaken_not_stirred cocktails api + shaken_not_stirred cocktails api
```ruby @@ -280,7 +368,7 @@ filter.results "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://ramshacklepantry.com/wp-content/uploads/2017/08/new_feature.jpg", + "image_large_url": "https://upload.wikimedia.org/wikipedia/commons/0/01/Mojito98775.jpeg", "video_url": "https://www.youtube.com/watch?v=_9v34KLET0g" } ... @@ -293,4 +381,4 @@ Questions or problems? Please post them on the [issue tracker](https://github.co ## 5. Copyright -Copyright © 2020 Juan Roldan. See [LICENSE.txt](https://github.com/juanroldan1989/shaken_not_stirred/blob/master/LICENSE.txt) for further details. +Copyright © 2023 Juan Roldan. See [LICENSE.txt](https://github.com/juanroldan1989/shaken_not_stirred/blob/master/LICENSE.txt) for further details.