api

func ChangeName ¶

func ChangeName(env *handler.Environment) httprouter.Handle

ChangeName creates a new username for the user identified by the current session. The request body is empty, all the username logic is performed on the server. The new name is returned on success.

Endpoint:

/api/v1/name

Methods:

PUT

Possible status codes:

200 - Success
404 - User doesn't exist or session is invalid
500 - Internal server error

Example output:

{ "id": 1, "name": "BadApple" }

func DeleteRecipeInstructions ¶

func DeleteRecipeInstructions(env *handler.Environment) httprouter.Handle

DeleteRecipeInstructions removes the preparation instructions for the recipe identified by the {id} parameter along with all associated static files, like images and video. Any data in the request body is ignored. The response body will always be empty, success or failure is communicated by the status codes.

No error will be returned if the recipe or instructions for the recipe don't exist.

Endpoint:

/api/v1/recipe/{id}/instructions

Methods:

DELETE

Possible status codes:

204 - Deletion successful
401 - Insufficient permission
500 - Internal server error

Example input:

inst=Cook+it+well!

func DeleteUser ¶

func DeleteUser(env *handler.Environment) httprouter.Handle

DeleteUser deletes the user account identified by the current session. If successful, the session cookie will also be deleted following an instant logout.

Endpoint:

/api/v1/user

Methods:

DELETE

Possible status codes:

200 - Success
404 - User is not logged in
500 - Internal server error

func Diary ¶

func Diary(env *handler.Environment) httprouter.Handle

Diary returns a JSON-formatted list of objects that summarize days from a user's diary. If no query parameters are provided, the entire diary is returned, otherwise only those dates that match {year} and {month}. The function body is empty when errors occur and will always be an array on success, even when there are no entries in the database.

Endpoint:

/api/v1/diary/{year}/{month}

Methods:

GET

Possible status codes:

200 - OK
400 - Malformed query parameters
401 - Insufficient permission
400 - Diary doesn't exist
500 - Internal server error

Example output:

[
  { "date": "2022-03-12", "kcal": 1987, ... },
  { "date": "2022-03-13", "kcal": 2150, ... },
  ...
]

func DiaryEntries ¶

func DiaryEntries(env *handler.Environment) httprouter.Handle

DiaryEntries returns a JSON-formatted list of food that is recorded in a user's diary. The date params are not optional. The function body is empty when errors occur and will always be an array on success, even when there are no entries in the database.

Endpoint:

/api/v1/diary/{year}/{month}/{day}/entries

Methods:

GET

Possible status codes:

200 - OK
400 - Malformed query parameters
401 - Insufficient permission
500 - Internal server error

Example output:

[
  "date": "2022-03-12T08:43:00Z", "food":{"id": 2, "amount": 150}, ...
  "date": "2022-03-12T13:05:00Z", "food":{"id": 1, "amount": 240}, ...
  ...
]

func Food ¶

func Food(env *handler.Environment) httprouter.Handle

Food returns a JSON-formatted food item identified by {id}. The function body is empty when errors occur and will be a single JSON object on success.

Endpoint:

/api/v1/food/{id}

Methods:

GET

Possible status codes:

200 - OK
400 - Missing or malformed id
404 - Food item doesn't exist
500 - Internal server error

Example output:

{ "id": 1, "kcal": 230, ... }

func Foods ¶

func Foods(env *handler.Environment) httprouter.Handle

Foods returns a JSON-formatted list of food items stored in the database. If no query parameters are transmitted, it returns the entire database. The function body is empty when errors occur and will always be an array on success, even when there are no food items in the database.

If a query parameter is included more than once, its first two values are interpreted as the minimum and the maximum valid amount.

Endpoint:

/api/v1/foods

Methods:

GET

Possible status codes:

200 - OK
500 - Internal server error

Example input:

kcal=32&kcal=120&prot=12

Example output:

[
  { "id": 1, "kcal": 230, ... },
  { "id": 6, "kcal": 522, ... },
  ...
]

func L10n ¶

func L10n(env *handler.Environment) httprouter.Handle

L10n returns all localized strings for the language {lang}. The response body will be a JSON-formatted collection of key-value pairs.

Endpoint:

/api/v1/l10n/{lang}

Methods:

GET

Possible status codes:

200 - OK

Example output:

{
  "app.name": "HeyApple",
  "msg.hello": "What's up?",
  ...
}

func NewFood ¶

func NewFood(env *handler.Environment) httprouter.Handle

NewFood creates a new food item and returns an empty food object with the new id on success. The response body will be empty if any errors occur.

Endpoint:

/api/v1/food

Methods:

POST

Possible status codes:

201 - Creation successful
401 - Insufficient permissions
500 - Internal server error

Example output:

{ "id": 2, "kcal": 0, "fat": 0, ... }

func NewRecipe ¶

func NewRecipe(env *handler.Environment) httprouter.Handle

NewRecipe creates a new named recipe and returns its ID on success. The response body will be empty if any errors occur.

Endpoint:

/api/v1/recipe

Methods:

POST

Possible status codes:

201 - Creation successful
202 - Partial success
400 - Missing form data
401 - Insufficient permission
500 - Internal server error

Example input:

name=Pie

Example output:

{ "id": 1, "size": 0, "items": [] }

func NewUser ¶

func NewUser(env *handler.Environment) httprouter.Handle

NewUser creates a new user and sends out a registration notification on success. The response body is always empty. For security reasons, this is one of a handful of functions that return success status codes even when technically failing. This is done to make user enumeration more difficult.

Endpoint:

/api/v1/user

Methods:

POST

Possible status codes:

202 - Creation request accepted
400 - Malformed or missing form data
422 - The provided password is not strong enough
500 - Internal server error

Example input:

email=user@example.com&pass=topsecret

func Preferences ¶

func Preferences(env *handler.Environment) httprouter.Handle

Preferences returns the account and app settings for the session user.

Endpoint:

/api/v1/prefs

Methods:

GET

Possible status codes:

200 - OK
404 - User doesn't exist
500 - Internal server error

Example output:

{
  "account": { "email": "user@example.com", ... },
  "rdi": { "kcal": 2000, "fat": 60, ... },
  ...
}

func Recipe ¶

func Recipe(env *handler.Environment) httprouter.Handle

Recipe returns a JSON-formatted recipe identified by {id}. The function body is empty when errors occur and will be a single JSON object on success.

Endpoint:

/api/v1/recipe/{id}

Methods:

GET

Possible status codes:

200 - OK
400 - Missing or malformed id
401 - Insufficient permission
404 - Recipe doesn't exist
500 - Internal server error

Example output:

{ "id": 1, "name": "Pie", "size": 6, ... }

func RecipeInstructions ¶

func RecipeInstructions(env *handler.Environment) httprouter.Handle

RecipeInstructions returns instructions on preparing the recipe identified by {id}. The function body is empty when errors occur and will be a single JSON object on success.

Endpoint:

/api/v1/recipe/{id}/instructions

Methods:

GET

Possible status codes:

200 - OK
400 - Missing or malformed id
401 - Insufficient permission
404 - Instructions don't exist
500 - Internal server error

Example output:

{ "inst": "Chop it all, put it in a bowl, heat up, eat." }

func RecipeOwner ¶

func RecipeOwner(env *handler.Environment) httprouter.Handle

RecipeOwner returns ownership information about the recipe identified by {id}. The function body is empty when errors occur and will be a single JSON object on success.

Endpoint:

/api/v1/recipe/{id}/owner

Methods:

GET

Possible status codes:

200 - OK
400 - Missing or malformed id
404 - Recipe doesn't exist
500 - Internal server error

Example output:

{ "isowner": false, "owner": "NastyOrange" }

func Recipes ¶

func Recipes(env *handler.Environment) httprouter.Handle

Recipes returns a JSON-formatted list of recipes stored in the database. If no query parameters are transmitted, it returns all recipes that the session user has access to. The function body is empty when errors occur and will always be an array on success, even when there are no recipes in the database.

If a query parameter is included more than once, its first two values are interpreted as the minimum and the maximum valid amount.

Endpoint:

/api/v1/recipes

Methods:

GET

Possible status codes:

200 - OK
500 - Internal server error

Example input:

name=Pie&kcal=32&kcal=120&prot=12

Example output:

[
  { "id": 1, "name": "Pie", "size": 6, ... },
  { "id": 6, "name": "Omelette", "size": 1, ... },
  ...
]

func SaveDiaryEntry ¶

func SaveDiaryEntry(env *handler.Environment) httprouter.Handle

SaveDiaryEntry edits food in the diary on the day identified by {date}. Time, food id, amount, and recipe name are passed in the request body. The response body will always be empty, success or failure is communicated by the status codes.

Food items that do not fit the date are just ignored without returning an error. POST adds the given amount to the amount of an existing item while PUT replaces it.

Date is expected to be in YYYY-MM-DD format, the time in simplified 24-hour hh:mm format. Any food item that does not conform to this will be ignored.

Endpoint:

/api/v1/diary/{date}

Methods:

POST, PUT

Possible status codes:

204 - Update successful
400 - Malformed or missing form data
401 - Insufficient permission
404 - Diary doesn't exist
500 - Internal server error

Example input:

recipe=Pie&id=1&amount=125&date=2022-03-12T12:45:00

func SaveFood ¶

func SaveFood(env *handler.Environment) httprouter.Handle

SaveFood updates a food item in the database identified by the {id} parameter. The nutrient values are passed in the request body. The response body will always be empty, success or failure is communicated by the status codes.

Invalid form data does not trigger an error and will just be dropped silently. As long as data is valid and corresponds to an existing nutrient, it's parsed and stored.

Endpoint:

/api/v1/food/{id}

Methods:

PUT

Possible status codes:

204 - Update successful
400 - Malformed form data
401 - Insufficient permissions
404 - Food item doesn't exist
500 - Internal server error

Example input:

kcal=123&fat=4.5&vitb1=0.06

func SaveIngredient ¶

func SaveIngredient(env *handler.Environment) httprouter.Handle

SaveIngredient adds the ingredient identified by {ing} to the recipe identified by {id}. The amount is passed in the request body. The response body will always be empty, success or failure is communicated by the status codes.

If the ingredient does not exist in the database, it is just ignored without returning an error. POST adds the given amount to the amount of an existing ingredient while PUT replaces it.

Endpoint:

/api/v1/recipe/{id}/ingredient/{ing}

Methods:

POST, PUT

Possible status codes:

204 - Update successful
400 - Malformed or missing form data
401 - Insufficient permission
404 - Recipe doesn't exist
500 - Internal server error

Example input:

amount=125

func SaveListDone ¶

func SaveListDone(env *handler.Environment) httprouter.Handle

SaveListDone enables or disables items on the shopping list identified by {name}. Disabled here represents the "already bought" state. The response body will always be empty, success or failure is communicated by the status codes.

Endpoint:

/api/v1/list/{name}/done

Methods:

Put

Possible status codes:

204 - Update successful
400 - Malformed or missing input data
401 - Insufficient permission
500 - Internal server error

Example input:

id=1&done=true&id=23&done=false

func SaveRecipe ¶

func SaveRecipe(env *handler.Environment) httprouter.Handle

SaveRecipe updates a recipe in the database identified by the {id} parameter. The data is passed in the request body. The response body will always be empty, success or failure is communicated by the status codes.

This endpoint does not update the list of ingredients!

Invalid form data does not trigger an error and will just be dropped silently. As long as data is valid and corresponds to an existing recipe, it's parsed and stored.

Endpoint:

/api/v1/recipe/{id}

Methods:

PUT

Possible status codes:

204 - Update successful
400 - Malformed or missing form data
401 - Insufficient permission
404 - Recipe doesn't exist
500 - Internal server error

Example input:

size=12&name=Butterscotch

func SaveRecipeInstructions ¶

func SaveRecipeInstructions(env *handler.Environment) httprouter.Handle

SaveRecipeInstructions updates the preparation instructions for the recipe identified by the {id} parameter. The data is passed in the request body. The response body will always be empty, success or failure is communicated by the status codes.

Passing an empty string is not allowed and will return an error. If you want to remove or reset instructions, use DeleteRecipeInstructions.

Endpoint:

/api/v1/recipe/{id}/instructions

Methods:

POST

Possible status codes:

204 - Update successful
400 - Malformed or missing form data
401 - Insufficient permission
404 - Recipe doesn't exist
500 - Internal server error

Example input:

inst=Cook+it+well!

func ShoppingList ¶

func ShoppingList(env *handler.Environment) httprouter.Handle

ShoppingList returns a JSON-formatted list of shopping items generated from a user's diary. It expects at least one valid date in the request body in the yyyy-mm-dd format. The response body is empty when errors occur and will always be an array on success, even when there are no entries in the database.

Endpoint:

/api/v1/list/{name}

Methods:

GET

Possible status codes:

200 - OK
400 - Malformed or missing query parameters
401 - Insufficient permission
404 - Shopping list doesn't exist
500 - Internal server error

Example input:

date=2022-03-12&date=2022-03-13

Example output:

[
  "id": "1", "amount": 150, "aisle": 12, "done": false, ...
  "id": "4", "amount": 620, "aisle": 9, "done": true, ...
  ...
]

func ShoppingLists ¶

func ShoppingLists(env *handler.Environment) httprouter.Handle

ShoppingLists returns a JSON-formatted list with the names of a user's custom shopping lists.

Endpoint:

/api/v1/lists

Methods:

GET

Possible status codes:

200 - OK
401 - Insufficient permission
500 - Internal server error

Example output:

[ "Dinner", "Cleaning Stuff", ... ]