---

• Mealchemy API Service Contracts
  • Table of Contents
  • 1. Authentication Services
    • User Registration Service:
    • User Login Service
    • User Logout Service
  • 2. Preference Services:
    • Get User Preferences Service
    • Update User Preferences Service
  • 3. Vault Services:
    • Get Vaults By Owner
    • Get Vault By ID
    • Create Vault
    • Update Vault
    • Delete Vault
  • 4. Vault Folder Services:
    • Get Folders By Vault ID
    • Get Folder By Name
    • Get Folder By ID
    • Create Vault Folder
    • Update Vault Folder
    • Delete Vault Folder
  • 5. Vault Folder Recipe Services
    • Get Recipes By Folder ID
    • Get Folders By Recipe ID
    • Get Folder Recipe By ID
    • Create Vault Folder Recipe
    • Update Vault Folder Recipe
    • Delete Vault Folder Recipe
  • 6. Pantry Services
    • Get User Pantry Ingredients
    • Add New Pantry Ingredient
    • Update Existing Pantry Ingredient
    • Delete Existing Pantry Ingredient
    • Search Pantry Ingredient By Name

---

Description: Registers a new user account and returns an authentication token.

Endpoint: POST /auth/register

Inputs:

Name	Type	Description
email	string	A valid, non-blank email address
password	string	User's password, minimum 8 characters
displayName	string	User's display name, max 80 characters

Outputs:

Name	Type	Description
user_id	integer	The newly created user's unique identifier
token	string	Access token for authenticated requests
onboarding_required	boolean	Whether the user still needs to complete onboarding

Usage / Interaction Rules:

• Send a POST request to /auth/register with email, password, and displayName in JSON format
• Returns 201 Created on success
• Returns 400 Bad Request if validation fails (e.g. invalid email)

---

Description: Authenticates an existing user and returns an access token.

Endpoint: POST /auth/login

Inputs:

Name	Type	Description
email	string	A valid, non-blank email address
password	string	User's non-blank password

Outputs:

Name	Type	Description
user_id	integer	The authenticated user's unique identifier
token	string	Access token for authenticated requests
onboarding_required	boolean	Whether the user still needs to complete onboarding

Usage / Interaction Rules:

• Send a POST request to /auth/login with email and password in JSON format
• Returns 200 OK on success
• Returns 401 Unauthorized if credentials are invalid

---

Description: Terminates the current user's authenticated session.

Endpoint: POST /auth/logout

Inputs: None

Outputs: None

Usage / Interaction Rules:

• Send a POST request to /auth/logout - no request body required
• Returns 204 No Content on success

---

Description: Retrieves the dietary preferences and restrictions for the authenticated user.

Endpoint: GET /user/preferences

Inputs:

Name	Type	Description
userId	string	Extracted automatically from the JWT token via @AuthenticationPrincipal

Outputs:

Name	Type	Description
dietary_restrictions	List<string>	User's dietary restrictions (e.g. vegan, halal)
allergies	List<string>	User's listed allergies
disliked_ingredients	List<string>	Ingredients the user wants excluded
flavour_profile	List<string>	User's preferred flavour profiles

Usage / Interaction Rules:

• Send a GET request to /user/preferences - no request body required
• Caller must be authenticated; JWT token must be present in the request header
• Returns 200 OK with the user's current preferences

---

Description: Replaces the authenticated user's dietary preferences with the provided values.

Endpoint: PUT /user/preferences

Inputs:

Name	Type	Description
userId	string	Extracted automatically from the JWT token via @AuthenticationPrincipal
dietary_restrictions	List<string>	Updated dietary restrictions
allergies	List<string>	Updated allergies
disliked_ingredients	List<string>	Updated disliked ingredients
flavour_profile	List<string>	Updated flavour profiles

Outputs:

Name	Type	Description
dietary_restrictions	List<string>	Saved dietary restrictions
allergies	List<string>	Saved allergies
disliked_ingredients	List<string>	Saved disliked ingredients
flavour_profile	List<string>	Saved flavour profiles

Usage / Interaction Rules:

• Send a PUT request to /user/preferences with a JSON body containing any combination of the four preference fields
• Caller must be authenticated; JWT token must be present in the request header
• Returns 200 OK with the full updated preferences object

---

Description: Retrieves all vaults belonging to a specific owner.

Endpoint: GET /vaults/owner/{ownerId}

Inputs:

Name	Type	Description
ownerId	integer	Path variable identifying the owner

Outputs:

Name	Type	Description
vault_id	integer	Unique vault identifier
owner_id	integer	ID of the vault's owner
vault_type	VaultType (enum)	Type/category of the vault
name	string	Name of the vault
created_at	OffsetDateTime	Timestamp of vault creation

Usage / Interaction Rules:

• Send a GET request to /vaults/owner/{ownerId}
• Returns 200 OK with a list of vaults

---

Description: Retrieves a single vault by its unique identifier.

Endpoint: GET /vaults/{id}

Inputs:

Name	Type	Description
id	integer	Path variable for the vault

Outputs:

Name	Type	Description
vault_id	integer	Unique vault identifier
owner_id	integer	ID of the vault's owner
vault_type	VaultType (enum)	Type/category of the vault
name	string	Name of the vault
created_at	OffsetDateTime	Timestamp of vault creation

Usage / Interaction Rules:

• Send a GET request to /vaults/{id}
• Returns 200 OK with the vault object

---

Description: Creates a new vault for a given owner.

Endpoint: POST /vaults

Inputs:

Name	Type	Description
owner_id	integer	The owner of the vault
vault_type	VaultType (enum)	Type/category of the vault
name	string	Name of the vault

Outputs:

Name	Type	Description
vault_id	integer	Unique vault identifier
owner_id	integer	ID of the vault's owner
vault_type	VaultType (enum)	Type/category of the vault
name	string	Name of the vault
created_at	OffsetDateTime	Timestamp of vault creation

Usage / Interaction Rules:

• Send a POST request to /vaults with owner_id, vault_type, and name in JSON format
• Returns 200 OK with the created vault

---

Description: Replaces an existing vault's details with the provided values.

Endpoint: PUT /vaults/{id}

Inputs:

Name	Type	Description
id	integer	Path variable for the vault to update
owner_id	integer	Updated owner ID
vault_type	VaultType (enum)	Updated vault type
name	string	Updated vault name

Outputs:

Name	Type	Description
vault_id	integer	Unique vault identifier
owner_id	integer	ID of the vault's owner
vault_type	VaultType (enum)	Type/category of the vault
name	string	Name of the vault
created_at	OffsetDateTime	Timestamp of vault creation

Usage / Interaction Rules:

• Send a PUT request to /vaults/{id} with updated fields in JSON format
• Returns 200 OK with the updated vault

---

Description: Permanently deletes a vault by its ID.

Endpoint: DELETE /vaults/{id}

Inputs:

Name	Type	Description
id	integer	Path variable for the vault to delete

Outputs: None

Usage / Interaction Rules:

• Send a DELETE request to /vaults/{id}
• Returns 200 OK (no body)

---

Description: Retrieves all folders within a specific vault.

Endpoint: GET /folders/vault/{vaultId}

Inputs:

Name	Type	Description
vaultId	integer	Path variable identifying the vault

Outputs:

Name	Type	Description
folder_id	integer	Unique folder identifier
vault_id	integer	ID of the parent vault
folder_name	string	Name of the folder
created_at	OffsetDateTime	Timestamp of folder creation

Usage / Interaction Rules:

• Send a GET request to /folders/vault/{vaultId}
• Returns 200 OK with a list of folders

---

Description: Retrieves a single vault folder by its name.

Endpoint: GET /folders/folder/name/{name}

Inputs:

Name	Type	Description
name	string	Path variable for the folder name

Outputs:

Name	Type	Description
folder_id	integer	Unique folder identifier
vault_id	integer	ID of the parent vault
folder_name	string	Name of the folder
created_at	OffsetDateTime	Timestamp of folder creation

Usage / Interaction Rules:

• Send a GET request to /folders/folder/name/{name}
• Returns 200 OK with the matched folder

---

Description: Retrieves a single vault folder by its unique identifier.

Endpoint: GET /folders/folder/{id}

Inputs:

Name	Type	Description
id	integer	Path variable for the folder

Outputs:

Name	Type	Description
folder_id	integer	Unique folder identifier
vault_id	integer	ID of the parent vault
folder_name	string	Name of the folder
created_at	OffsetDateTime	Timestamp of folder creation

Usage / Interaction Rules:

• Send a GET request to /folders/folder/{id}
• Returns 200 OK with the folder object

---

Description: Creates a new folder within a specified vault.

Endpoint: POST /folders

Inputs:

Name	Type	Description
vault_id	integer	The vault to create the folder in
folder_name	string	Name of the new folder

Outputs:

Name	Type	Description
folder_id	integer	Unique folder identifier
vault_id	integer	ID of the parent vault
folder_name	string	Name of the folder
created_at	OffsetDateTime	Timestamp of folder creation

Usage / Interaction Rules:

• Send a POST request to /folders with vault_id and folder_name in JSON format
• Returns 200 OK with the created folder

---

Description: Updates an existing folder's details.

Endpoint: PUT /folders/{id}

Inputs:

Name	Type	Description
id	integer	Path variable for the folder to update
vault_id	integer	Updated parent vault ID
folder_name	string	Updated folder name

Outputs:

Name	Type	Description
folder_id	integer	Unique folder identifier
vault_id	integer	ID of the parent vault
folder_name	string	Name of the folder
created_at	OffsetDateTime	Timestamp of folder creation

Usage / Interaction Rules:

• Send a PUT request to /folders/{id} with updated fields in JSON format
• Returns 200 OK with the updated folder

---

Description: Permanently deletes a folder by its ID.

Endpoint: DELETE /folders/{id}

Inputs:

Name	Type	Description
id	integer	Path variable for the folder to delete

Outputs: None

Usage / Interaction Rules:

• Send a DELETE request to /folders/{id}
• Returns 200 OK (no body)

---

Description: Retrieves all recipe entries associated with a specific folder.

Endpoint: GET /recipefolders/recipes/{folderId}

Inputs:

Name	Type	Description
folderId	integer	Path variable identifying the folder

Outputs:

Name	Type	Description
id	integer	Unique ID of the association record
folder_id	integer	The folder the recipe belongs to
recipe_id	integer	The linked recipe
added_at	OffsetDateTime	When the recipe was added to the folder

Usage / Interaction Rules:

• Send a GET request to /recipefolders/recipes/{folderId}
• Returns 200 OK with a list of recipe-folder associations

---

Description: Retrieves all folder entries that contain a specific recipe.

Endpoint: GET /recipefolders/folders/{recipeId}

Inputs:

Name	Type	Description
recipeId	integer	Path variable identifying the recipe

Outputs:

Name	Type	Description
id	integer	Unique ID of the association record
folder_id	integer	The folder the recipe belongs to
recipe_id	integer	The linked recipe
added_at	OffsetDateTime	When the recipe was added to the folder

Usage / Interaction Rules:

• Send a GET request to /recipefolders/folders/{recipeId}
• Returns 200 OK with a list of folder-recipe associations

---

Description: Retrieves a single folder-recipe association by its ID.

Endpoint: GET /recipefolders/{id}

Inputs:

Name	Type	Description
id	integer	Path variable for the association record

Outputs:

Name	Type	Description
id	integer	Unique ID of the association record
folder_id	integer	The folder the recipe belongs to
recipe_id	integer	The linked recipe
added_at	OffsetDateTime	When the recipe was added to the folder

Usage / Interaction Rules:

• Send a GET request to /recipefolders/{id}
• Returns 200 OK

---

Description: Links a recipe to a folder by creating a new association record.

Endpoint: POST /recipefolders

Inputs:

Name	Type	Description
folder_id	integer	The folder to link to
recipe_id	integer	The recipe to link

Outputs:

Name	Type	Description
id	integer	Unique ID of the association record
folder_id	integer	The folder the recipe belongs to
recipe_id	integer	The linked recipe
added_at	OffsetDateTime	When the recipe was added to the folder

Usage / Interaction Rules:

• Send a POST request to /recipefolders with folder_id and recipe_id in JSON format
• Returns 200 OK with the created association record

---

Description: Updates an existing folder-recipe association.

Endpoint: PUT /recipefolders/{id}

Inputs:

Name	Type	Description
id	integer	Path variable for the association to update
folder_id	integer	Updated folder ID
recipe_id	integer	Updated recipe ID

Outputs:

Name	Type	Description
id	integer	Unique ID of the association record
folder_id	integer	The folder the recipe belongs to
recipe_id	integer	The linked recipe
added_at	OffsetDateTime	When the recipe was added to the folder

Usage / Interaction Rules:

• Send a PUT request to /recipefolders/{id} with updated fields in JSON format
• Returns 200 OK with the updated association record

---

Description: Removes a folder-recipe association by its ID.

Endpoint: DELETE /recipefolders/{id}

Inputs:

Name	Type	Description
id	integer	Path variable for the association to delete

Outputs: None

Usage / Interaction Rules:

• Send a DELETE request to /recipefolders/{id}
• Returns 200 OK (no body)

---

Description: Retrieves all pantry ingredients that belong to the logged-in user.

Endpoint: GET /api/pantry

Inputs:

Name	Type	Description
userId	string	Extracted automatically from the JWT token via @AuthenticationPrincipal

Outputs:

Name	Type	Description
p_ingredient_id	integer	Unique ID of the pantry ingredient record
ing_id	integer	Foreign key that uniquely identifies ingredients from the ingredient catalogue
name	string	The ingredient name
category	string	The food category the ingredient belongs to
quantity	BigDecimal	The amount of the ingredient
unit	string	The unit of measurement of the amount
created_at	OffsetDateTime	When the ingredient was added to the pantry
updated_at	OffsetDateTime	When the pantry ingredient was most recently updated

Usage / Interaction Rules:

• Send a GET request to /api/pantry
• Returns 200 OK with the pantry ingredient information

---

Description: Manually adds a new ingredient to the logged-in user's pantry

Endpoint: POST /api/pantry

Inputs:

Name	Type	Description
userId	string	Extracted automatically from the JWT token via @AuthenticationPrincipal
ing_id	integer	Foreign key that uniquely identifies ingredients from the ingredient catalogue
quantity	BigDecimal	The amount of the ingredient
unit	string	The unit of measurement of the amount

Outputs:

Name	Type	Description
p_ingredient_id	integer	Unique ID of the pantry ingredient record
ing_id	integer	Foreign key that uniquely identifies ingredients from the ingredient catalogue
name	string	The ingredient name
category	string	The food category the ingredient belongs to
quantity	BigDecimal	The amount of the ingredient
unit	string	The unit of measurement of the amount
created_at	OffsetDateTime	When the ingredient was added to the pantry
updated_at	OffsetDateTime	When the pantry ingredient was most recently updated

Usage / Interaction Rules:

• Send a POST request to /api/pantry
• Quantity should be greater than zero
• Returns 200 OK with the pantry ingredient information

---

Description: Manually updates an existing ingredient in the logged-in user's pantry

Endpoint: PUT /api/pantry/{id}

Inputs:

Name	Type	Description
userId	string	Extracted automatically from the JWT token via @AuthenticationPrincipal
p_ingredient_id	integer	Unique ID of the pantry ingredient record
ing_id	integer	Foreign key that uniquely identifies ingredients from the ingredient catalogue
quantity	BigDecimal	The amount of the ingredient
unit	string	The unit of measurement of the amount

Outputs:

Name	Type	Description
p_ingredient_id	integer	Unique ID of the pantry ingredient record
ing_id	integer	Foreign key that uniquely identifies ingredients from the ingredient catalogue
name	string	The ingredient name
category	string	The food category the ingredient belongs to
quantity	BigDecimal	The amount of the ingredient
unit	string	The unit of measurement of the amount
created_at	OffsetDateTime	When the ingredient was added to the pantry
updated_at	OffsetDateTime	When the pantry ingredient was most recently updated

Usage / Interaction Rules:

• Send a PUT request to /api/pantry/{id}
• Users can only update their own pantry items
• Returns 200 OK with the pantry ingredient information

---

Description: Manually deletes an existing ingredient in the logged-in user's pantry

Endpoint: DELETE /api/pantry/{id}

Inputs:

Name	Type	Description
userId	string	Extracted automatically from the JWT token via @AuthenticationPrincipal
p_ingredient_id	integer	Unique ID of the pantry ingredient record

Outputs: None

Usage / Interaction Rules:

• Sends a DELETE request to /api/pantry/{id}
• Users can only delete their own pantry items
• Deleted items should o longer appear in pantry ingredient lists or in recommendation engine pantry comparison
• Returns 204 OK with no response body

---

Description: Searches the logged in user's pantry by ingredient name

Endpoint: GET /api/pantry/search?q={query}

Inputs:

Name	Type	Description
userId	string	Extracted automatically from the JWT token via @AuthenticationPrincipal
q	string	Pantry Ingredient name

Outputs:

Name	Type	Description
p_ingredient_id	integer	Unique ID of the pantry ingredient record
ing_id	integer	Foreign key that uniquely identifies ingredients from the ingredient catalogue
name	string	The ingredient name
category	string	The food category the ingredient belongs to
quantity	BigDecimal	The amount of the ingredient
unit	string	The unit of measurement of the amount
created_at	OffsetDateTime	When the ingredient was added to the pantry
updated_at	OffsetDateTime	When the pantry ingredient was most recently updated

Usage / Interaction Rules:

• Send a GET request to /api/pantry/search?q={query}
• Returns 200 OK with the pantry ingredient information