Skip to content

REST API contracts

GET /groceries
DELETE /groceries
POST /groceries
DELETE /groceries/{itemId}
PATCH /groceries/{itemId}
POST /groceries/check
POST /groceries/generate
GET /plans
PATCH /plans/current
DELETE /plans/{planNR}
POST /meals
DELETE /meals/{itemId}
PATCH /meals/{itemId}
GET /ingredients
DELETE /ingredients
POST /ingredients
DELETE /ingredients/{itemId}
PATCH /ingredients/{itemId}
POST /ingredients/import
POST /ideas/generate
GET /ideas
DELETE /ideas
GET /preferences
PATCH /preferences
GET /tasks/{taskId}

Groceries

Get groceries list

Get the list of all items in the groceries list of each week day.

Items are returned in a dictionary where the item IDs are the key for an object with other item's data. Week day is represented as an integer between 0 and 6.

Request

GET /groceries

Response

  • 200: grocery items found
{
    "groceries": {
        "id-1": {
            "description": string,
            "weekDay": int,
            "checked": bool
        },
        "id-2": {
            "description": string,
            "weekDay": int,
            "checked": bool
        }
    }
}

Clear groceries

Delete all items in the user's groceries list. This request is idempotent: it doesn't fail if list is already empty.

Request

DELETE /groceries

Response

  • 204: all items deleted successfully

Add new item

Add a new element manually in the groceries list.

Week day must be represented by an integer between 0 and 6.

Request

POST /groceries

{
    "description": string,
    "weekDay": int
}

Response

  • 201: new item created
  • 400: invalid field
{
    "itemId": string
}

Delete item

Delete an item from the groceries list.

Request

DELETE /groceries/{itemId}

Response

  • 204: item deleted successfully
  • 404: item not found

Edit item state

Edit fields of an item in the groceries list. Fields may be the description, or the check-box state. Omitted fields are ignored (not updated).

Request

PATCH /groceries/{itemId}

{
    "description": string,
    "checked": bool
}

Response

  • 204: fields updated successfully
  • 400: invalid field
  • 404: item not found

Check or uncheck all items

Check or uncheck all items in the user's groceries list in bulk. This request is idempotent: if all items are already checked/unchecked it doesn't fail.

Request

POST /groceries/check

{
    "check": bool
}

Response

  • 204: operation successful

Generate items with AI

Based on input data (available days, chosen plan and extra infos) and based on user data in the backend (meals plan and preferences), a task for generating a list of grocery items with AI is started.

Generated items are not returned: to see the updated items list use the get groceries request when the operation concludes. To check the status of the task it is possible to poll the get status request with the returned task ID.

In the request schema, available days are represented as a list of integers, where Monday is 0 and Sunday is 6. To select a plan, the plan number (1 to 4) is sufficient, as the plan items are retrieved by the backend autonomously from the DB. Unplanned meals must be provided as a list of strings containing the meal description. Extra textual information is provided with a single string. If replace field is false, old items in the groceries list aren't deleted and new ones are simply appended.

Request

POST /groceries/generate

{
    "days": [ int ],
    "plan": int,
    "unplanned": [ string ],
    "extra": string,
    "replace": bool
}

Response

  • 202: generation task initialized
  • 400: invalid field
  • 404: plan not found (empty)
  • 409: a generation task is already executing for the user
  • 429: computation limit reached
{
    "taskId": string
}

Plans

Get plans

Get all the weekly meals plans registered by the user, alongside the one currently selected.

If user has just empty plans, then the current plan will be the first and it will be empty. Otherwise, empty plans are omitted.

Plans are returned in a dictionary where the key is the plan number shown in the UI (1-4). Each plan is itself a dictionary where the item IDs are the key for an object with other item's data. Items' icon identifies the Unicode value of an emoji. Week day is represented as an integer between 0 and 6.

Request

GET /plans

Response

  • 200: plans found
{
    "current": int,
    "plans": {
        "1": {
            "id-1": {
                "description": string,
                "icon": string,
                "weekDay": int
            },
            "id-2": {
                "description": string,
                "icon": string,
                "weekDay": int
            }
        },
        "2": {
            "id-3": {
                "description": string,
                "icon": string,
                "weekDay": int
            }
        }
    }
}

Set current plan

Set the number of the plan currently selected and active for the user.

The plan number is defined with an integer between 1 and 4.

Request

PATCH plans/current

{
    "current": int
}

Response

  • 204: current plan set
  • 400: invalid field
  • 404: plan not found (empty)

Delete plan

Clear the user's meals plan with the provided number (1-4). This request is idempotent: if the plan was already empty no error is returned.

After the plan is deleted, the next currently selected will be the first non-empty before the deleted one. If all plans get deleted, the currently selected one is the first, even if empty.

Request

DELETE /plans/{planNR}

Response

  • 204: plan deleted successfully

Meals

Add meal to plan

Create a new meal in a plan.

Items' icon must identify the Unicode value of an emoji. Week day must be represented by an integer between 0 and 6. The plan in which to add the meal is identified by a number from 1 to 4.

Request

POST /meals

{
    "description": string,
    "icon": string,
    "weekDay": int,
    "plan": int
}

Response

  • 201: new item created
  • 400: invalid field
{
    "itemId": string
}

Delete meal from plan

Delete a meal from its plan.

If the last item in the plan is deleted, the currently selected plan changes and will be the first non-empty before the emptied/deleted one. If all plans get deleted, the currently selected one is the first, even if empty.

Request

DELETE /meals/{itemId}

Response

  • 204: meal deleted successfully
  • 404: meal not found

Edit meal state

Edit the description or the emoji of a meal. Omitted fields are ignored (not updated).

Request

PATCH /meals/{itemId}

{
    "description": string,
    "icon": string
}

Response

  • 204: fields updated successfully
  • 400: invalid field
  • 404: meal not found

Ingredients

Get pantry ingredients

Get the list of ingredients already available in the pantry.

Items are returned in a dictionary where the item IDs are the key for an object with other item's data.

Request

GET /ingredients

Response

  • 200: pantry ingredient found
{
    "ingredients": {
        "id-1": {
            "description": string
        },
        "id-2": {
            "description": string
        }
    }
}

Clear pantry ingredients

Empty the list of available ingredients in the pantry. This request is idempotent: if the list is already empty, no error arises.

Request

DELETE /ingredients

Response

  • 204: all elements deleted

Add new ingredient

Add a new item in the pantry ingredients list.

Request

POST /ingredients

{
    "description": string
}

Response

  • 201: new item created
  • 400: invalid field
{
    "itemId": string
}

Delete ingredient

Delete an item from the pantry ingredients list.

Request

DELETE /ingredients/{itemId}

Response

  • 204: item deleted successfully
  • 404: item not found

Edit ingredient state

Edit the description of an item in the pantry ingredients list.

Request

PATCH /ingredients/{itemId}

{
    "description": string
}

Response

  • 204: field updated successfully
  • 400: invalid field
  • 404: item not found

Import from groceries

Take all items in the groceries list where the check-box is ticked and import them into the pantry ingredients list. Items with the same description are not duplicated. This request is idempotent: if no new item to be imported is found, no error arises.

Request

POST /ingredients/import

Response

  • 204: operation successful

Ideas

Get ideas

Get the list of previously generated meal suggestions (ideas). If ideas list was never generated or if it was cleared (thus absent) no error arises but the returned JSON payload doesn't contain the ideas key, thus being empty ({}).

Request

GET /ideas

Response

  • 200: data returned successfully
{
    "ideas": [
        {
            "name": string,
            "story": string,
            "icon": string
        },
        {
            "name": string,
            "story": string,
            "icon": string
        }
    ]
}

Clear ideas

Clear (delete) the ideas list. This request is idempotent: if the list was already empty no error is returned.

Request

DELETE /ideas

Response

  • 204: list deleted successfully

Generate ideas with AI

Starting from the list if ingredients found in the pantry and based on the user's preferences (already available in the backend), a task for generating a list of meal ideas with AI is started. Old ideas are deleted.

Generated ideas are not returned: to see the new ideas list use the get ideas request when the operation concludes. To check the status of the task it is possible to poll the get status request with the returned task ID.

In the request schema, extra textual information is provided with a string.

Request

POST /ideas/generate

{
    "extra": string
}

Response

  • 202: generation task initialized
  • 404: ingredients not found (empty list)
  • 409: a generation task is already executing for the user
  • 429: computation limit reached
{
    "taskId": string
}

Preferences

Get user preferences

Get the textual descriptions of user's preferences. Empty string is valid content, meaning that if the user has not set it, an empty string is returned with that specific preference key.

Request

GET /preferences

Response

  • 200: data returned successfully
{
    "preferences": {
        "dietary": string,
        "allergies": string,
        "disliked": string
    }
}

Update user preferences

Set a new textual description of user's preferences. An empty string is valid content, therefore this request can be used also to unset it, by sending an empty string with the desired preference key.

Omitted attributes are ignored, meaning they are not updated/cleared.

Request

PATCH /preferences

{
    "preferences": {
        "dietary": string,
        "allergies": string,
        "disliked": string
    }
}

Response

  • 204: preferences set successfully
  • 400: invalid field

Tasks

Get task status

The status of ongoing tasks in the server (such as content generation with AI) can be retrieved by polling this request. Please poll after at least 2 seconds of delay.

The status of a task is represented by an integer.

  • -1: task failed
  • 0: task is still running
  • 1: task completed successfully

Request

GET /tasks/{taskId}

Response

  • 200: task found
  • 404: task not found
{
    "status": int
}