api

package
v0.0.0-...-2d56da1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 10, 2024 License: AGPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package api implements a REST API to interact with the app over HTTP requests. This is v1 of the API.

All objects returned from the functions in this package are valid JSON values, including strings, numbers, objects, arrays, and null. Look at the documentation for individual functions to learn about API endpoints, possible status codes, and example output.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

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 SavePreferences 

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

SavePreferences saves the account and app settings for the session user. When successful, it returns the updated settings because changes to some settings can have an effect on others.

Endpoint: 

/api/v1/prefs

Methods: 

PUT

Possible status codes: 

200 - OK
400 - Malformed or missing form data
404 - User doesn't exist
500 - Internal server error

Example output: 

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

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", ... ]

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.