diff --git a/docs/docs/api-usage/bulk-url-import.md b/docs/docs/api-usage/bulk-url-import.md new file mode 100644 index 000000000000..130e42d9a775 --- /dev/null +++ b/docs/docs/api-usage/bulk-url-import.md @@ -0,0 +1,93 @@ +!!! info + This example was submitted by a user. Have an Example? Submit a PR! + + +Recipes can be imported in bulk from a file containing a list of URLs. This can be done using the following bash or python scripts with the `list` file containing one URL per line. + +#### Bash +```bash +#!/bin/bash + +function authentification () { + auth=$(curl -X 'POST' \ + "$3/api/auth/token" \ + -H 'accept: application/json' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'grant_type=&username='$1'&password='$2'&scope=&client_id=&client_secret=') + + echo $auth | sed -e 's/.*token":"\(.*\)",.*/\1/' +} + +function import_from_file () { + while IFS= read -r line + do + echo $line + curl -X 'POST' \ + "$3/api/recipes/create-url" \ + -H "Authorization: Bearer $2" \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{"url": "'$line'" }' + echo + done < "$1" +} + +input="list" +mail="changeme@email.com" +password="MyPassword" +mealie_url=http://localhost:9000 + + +token=$(authentification $mail $password $mealie_url) +import_from_file $input $token $mealie_url + +``` + +#### Python +```python +import requests +import re + +def authentification(mail, password, mealie_url): + headers = { + 'accept': 'application/json', + 'Content-Type': 'application/x-www-form-urlencoded', + } + data = { + 'grant_type': '', + 'username': mail, + 'password': password, + 'scope': '', + 'client_id': '', + 'client_secret': '' + } + auth = requests.post(mealie_url + "/api/auth/token", headers=headers, data=data) + token = re.sub(r'.*token":"(.*)",.*', r'\1', auth.text) + return token + +def import_from_file(input_file, token, mealie_url): + with open(input_file) as fp: + for l in fp: + line = re.sub(r'(.*)\n', r'\1', l) + print(line) + headers = { + 'Authorization': "Bearer " + token, + 'accept': 'application/json', + 'Content-Type': 'application/json' + } + data = { + 'url': line + } + response = requests.post(mealie_url + "/api/recipes/create-url", headers=headers, json=data) + print(response.text) + +input_file="list" +mail="changeme@email.com" +password="MyPassword" +mealie_url="http://localhost:9000" + + +token = authentification(mail, password, mealie_url) +import_from_file(input_file, token, mealie_url) +``` + diff --git a/docs/docs/api-usage/getting-started.md b/docs/docs/api-usage/getting-started.md new file mode 100644 index 000000000000..95abfd6a17bc --- /dev/null +++ b/docs/docs/api-usage/getting-started.md @@ -0,0 +1,39 @@ +# Usage + +## Getting a Token + +Currently Mealie doesn't support creating a long-live token. You can however get a token from the API. This example was pulled from the automatic API documentation provided by Mealie. + +### Curl +```bash +curl -X 'POST' \ + 'https://mealie-demo.hay-kot.dev/api/auth/token' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'grant_type=&username=changeme%40email.com&password=demo&scope=&client_id=&client_secret=' + +``` + +#### Response +```json +{ + "snackbar": { + "text": "User Successfully Logged In", + "type": "success" + }, + "access_token": "your-long-token-string", + "token_type": "bearer" +} +``` + +## Key Components + +### Exploring Your Local API +On your local installation you can access interactive API documentation that provides `curl` examples and expected results. This allows you to easily test and interact with your API to identify places to include your own functionality. You can visit the documentation at `http://mealie.yourdomain.com/docs or see the example at the [Demo Site](https://mealie-demo.hay-kot.dev/docs) + +### Recipe Extras +Recipes extras are a key feature of the Mealie API. They allow you to create custom json key/value pairs within a recipe to reference from 3rd part applications. You can use these keys to contain information to trigger automation or custom messages to relay to your desired device. + +For example you could add `{"message": "Remember to thaw the chicken"}` to a recipe and use the webhooks built into mealie to send that message payload to a destination to be processed. + +![api-extras-gif](../assets/gifs/api-extras.gif) diff --git a/docs/docs/api-usage/home-assistant.md b/docs/docs/api-usage/home-assistant.md new file mode 100644 index 000000000000..4de60be82703 --- /dev/null +++ b/docs/docs/api-usage/home-assistant.md @@ -0,0 +1,30 @@ +In a lot of ways, Home Assistant is why this project exists! Since it Mealie has a robust API it makes it a great fit for interacting with Home Assistant and pulling information into your dashboard. + +### Get Todays Meal in Lovelace +Starting in v0.4.1 you are now able to use the uri `/api​/meal-plans​/today​/image?group_name=Home` to directly access the image to todays meal. This makes it incredible easy to include the image into your Home Assistant Dashboard using the picture entity. + +Here's an example where `sensor.mealie_todays_meal` is pulling in the meal-plan name and I'm using the url to get the image. + +![api-extras-gif](../assets/img/home-assistant-card.png) + +```yaml +type: picture-entity +entity: sensor.mealie_todays_meal +name: Dinner Tonight +show_state: true +show_name: true +image: 'http://localhost:9000/api/meal-plans/today/image?group_name=Home' +style: +.: | + ha-card { + max-height: 300px !important; + overflow: hidden; + display: flex; + align-items: center; + justify-content: center; + } +``` + + +!!! tip + Due to how Home Assistant works with images, I had to include the additional styling to get the images to not appear distorted. This includes and [additional installation](https://github.com/thomasloven/lovelace-card-mod) from HACS. diff --git a/docs/docs/assets/img/home-assistant-card.png b/docs/docs/assets/img/home-assistant-card.png new file mode 100644 index 000000000000..9a6e46acc50a Binary files /dev/null and b/docs/docs/assets/img/home-assistant-card.png differ diff --git a/docs/docs/getting-started/api-usage.md b/docs/docs/getting-started/api-usage.md index b58fc485fa90..f44a308317e5 100644 --- a/docs/docs/getting-started/api-usage.md +++ b/docs/docs/getting-started/api-usage.md @@ -1,5 +1,8 @@ # Usage +## Getting a Token +Bla Bla + ## Key Components ### Recipe Extras Recipes extras are a key feature of the Mealie API. They allow you to create custom json key/value pairs within a recipe to reference from 3rd part applications. You can use these keys to contain information to trigger automation or custom messages to relay to your desired device. @@ -8,96 +11,4 @@ For example you could add `{"message": "Remember to thaw the chicken"}` to a rec ![api-extras-gif](../assets/gifs/api-extras.gif) - -## Examples -### Bulk import -Recipes can be imported in bulk from a file containing a list of URLs. This can be done using the following bash or python scripts with the `list` file containing one URL per line. - -#### Bash -```bash -#!/bin/bash - -function authentification () { - auth=$(curl -X 'POST' \ - "$3/api/auth/token" \ - -H 'accept: application/json' \ - -H 'Content-Type: application/x-www-form-urlencoded' \ - -d 'grant_type=&username='$1'&password='$2'&scope=&client_id=&client_secret=') - - echo $auth | sed -e 's/.*token":"\(.*\)",.*/\1/' -} - -function import_from_file () { - while IFS= read -r line - do - echo $line - curl -X 'POST' \ - "$3/api/recipes/create-url" \ - -H "Authorization: Bearer $2" \ - -H 'accept: application/json' \ - -H 'Content-Type: application/json' \ - -d '{"url": "'$line'" }' - echo - done < "$1" -} - -input="list" -mail="changeme@email.com" -password="MyPassword" -mealie_url=http://localhost:9000 - - -token=$(authentification $mail $password $mealie_url) -import_from_file $input $token $mealie_url - -``` - -#### Python -```python -import requests -import re - -def authentification(mail, password, mealie_url): - headers = { - 'accept': 'application/json', - 'Content-Type': 'application/x-www-form-urlencoded', - } - data = { - 'grant_type': '', - 'username': mail, - 'password': password, - 'scope': '', - 'client_id': '', - 'client_secret': '' - } - auth = requests.post(mealie_url + "/api/auth/token", headers=headers, data=data) - token = re.sub(r'.*token":"(.*)",.*', r'\1', auth.text) - return token - -def import_from_file(input_file, token, mealie_url): - with open(input_file) as fp: - for l in fp: - line = re.sub(r'(.*)\n', r'\1', l) - print(line) - headers = { - 'Authorization': "Bearer " + token, - 'accept': 'application/json', - 'Content-Type': 'application/json' - } - data = { - 'url': line - } - response = requests.post(mealie_url + "/api/recipes/create-url", headers=headers, json=data) - print(response.text) - -input_file="list" -mail="changeme@email.com" -password="MyPassword" -mealie_url="http://localhost:9000" - - -token = authentification(mail, password, mealie_url) -import_from_file(input_file, token, mealie_url) -``` - Have Ideas? Submit a PR! diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 7d675172a133..ab46a17c748e 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -56,7 +56,6 @@ nav: - Organizing Recipes: "getting-started/organizing-recipes.md" - Planning Meals: "getting-started/meal-planner.md" - iOS Shortcuts: "getting-started/ios.md" - - API Usage: "getting-started/api-usage.md" - Site Administration: - User Settings: "site-administration/user-settings.md" - Site Settings: "site-administration/site-settings.md" @@ -64,6 +63,10 @@ nav: - User Management: "site-administration/user-management.md" - Backups and Restore: "site-administration/backups-and-exports.md" - Recipe Migration: "site-administration/migration-imports.md" + - API Usage: + - Getting Started: "api-usage/getting-started.md" + - Home Assistant: "api-usage/home-assistant.md" + - Bulk Url Import: "api-usage/bulk-url-import.md" - API Reference: "api/redoc.md" - Contributors Guide: - Non-Code: "contributors/non-coders.md" diff --git a/mealie/routes/mealplans/crud.py b/mealie/routes/mealplans/crud.py index f1dcc02bb220..de3085bdd8b1 100644 --- a/mealie/routes/mealplans/crud.py +++ b/mealie/routes/mealplans/crud.py @@ -79,7 +79,7 @@ def get_today(session: Session = Depends(generate_session), current_user: UserIn @router.get("/today/image", tags=["Meal Plan"]) -def get_today(session: Session = Depends(generate_session), group_name: str = "Home"): +def get_todays_image(session: Session = Depends(generate_session), group_name: str = "Home"): """ Returns the image for todays meal-plan. """