# Menus

Menu generation and breadcrumb navigation operations

## Generate Menu

> This method generates a hierarchical navigation menu based on the configured menu structure in the system.\
> \
> The endpoint retrieves menu items from the database, applies filters based on provided parameters, and processes them through the configured generators and modifiers to produce a complete menu structure.\
> \
> \*\*Depth Calculation:\*\*\
> \* \`start\_level\`: Defines the starting depth (0-based, excluding root)\
> \* \`depth\_height\`: Number of levels to retrieve from start\_level\
> \* Actual database depth = start\_level + 2 (root is depth 1, hidden from API)\
> \* Example: start\_level=0, depth\_height=2 retrieves levels 0 and 1 (database depths 2-3)\
> \
> \*\*Parent vs Sibling Parameters:\*\*\
> \* \`parent\`: Generates children of specified parent UUID\
>   \- Starts from parent's depth + 1\
>   \- Retrieves parent's descendants\
> \* \`sibling\`: Generates siblings of specified item UUID\
>   \- Starts from sibling's depth\
>   \- Retrieves items at same level under same parent\
> \* Cannot use both parameters simultaneously\
> \
> \*\*Use Cases:\*\*\
> \* Main navigation menu generation\
> \* Sidebar navigation with category tree\
> \* Mega menu with multiple levels\
> \* Mobile menu with hierarchical structure\
> \* Contextual navigation showing current location\
> \* Lazy-loading submenu items on demand

```json
{"openapi":"3.0.3","info":{"title":"Menu API","version":"1.0.0"},"tags":[{"name":"menus","description":"Menu generation and breadcrumb navigation operations"}],"servers":[{"description":"Server base URL for basket operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/menus/generate/":{"get":{"summary":"Generate Menu","description":"This method generates a hierarchical navigation menu based on the configured menu structure in the system.\n\nThe endpoint retrieves menu items from the database, applies filters based on provided parameters, and processes them through the configured generators and modifiers to produce a complete menu structure.\n\n**Depth Calculation:**\n* `start_level`: Defines the starting depth (0-based, excluding root)\n* `depth_height`: Number of levels to retrieve from start_level\n* Actual database depth = start_level + 2 (root is depth 1, hidden from API)\n* Example: start_level=0, depth_height=2 retrieves levels 0 and 1 (database depths 2-3)\n\n**Parent vs Sibling Parameters:**\n* `parent`: Generates children of specified parent UUID\n  - Starts from parent's depth + 1\n  - Retrieves parent's descendants\n* `sibling`: Generates siblings of specified item UUID\n  - Starts from sibling's depth\n  - Retrieves items at same level under same parent\n* Cannot use both parameters simultaneously\n\n**Use Cases:**\n* Main navigation menu generation\n* Sidebar navigation with category tree\n* Mega menu with multiple levels\n* Mobile menu with hierarchical structure\n* Contextual navigation showing current location\n* Lazy-loading submenu items on demand","operationId":"generate_menu","parameters":[{"name":"depth_height","in":"query","required":true,"description":"Number of levels to retrieve from the starting point.\n\n* Value of 1 retrieves only the immediate children\n* Value of 2 retrieves children and grandchildren\n* Combined with start_level to define the depth range\n* Example: start_level=0, depth_height=2 retrieves levels 0-1","schema":{"type":"integer","minimum":1}},{"name":"parent","in":"query","required":false,"description":"UUID of the parent menu item to start generation from.\n\n* When provided, generates children of this parent\n* Overrides MENU_DEFAULT_PARENT_UUID setting\n* Cannot be used with sibling parameter\n* If parent not found, returns empty array\n* Null value allows root-level generation","schema":{"type":"string","format":"uuid","nullable":true}},{"name":"sibling","in":"query","required":false,"description":"UUID of a menu item to generate siblings for.\n\n* Generates items at the same level under the same parent\n* Useful for horizontal navigation or related sections\n* Cannot be used with parent parameter\n* If sibling not found, returns empty array","schema":{"type":"string","format":"uuid"}},{"name":"start_level","in":"query","required":false,"description":"Starting depth level for menu generation (0-based, excluding root).\n\n* Default: 0 (top-level menu items)\n* Level 0 = first visible level\n* Level 1 = second level, and so on\n* Combined with depth_height to define range\n* If start_level > 0 and no parent determinable, returns empty array","schema":{"type":"integer","minimum":0,"default":0}},{"name":"include_parent","in":"query","required":false,"description":"Whether to include the parent node in the results.\n\n* When true, parent item is added to the end of the array\n* Useful for breadcrumb trails or showing context\n* Only applies when parent parameter is specified\n* Parent must be visible (visible=true)","schema":{"type":"boolean","default":false}},{"name":"request_path","in":"query","required":false,"description":"Current page URL path for context-aware menu highlighting.\n\n* System finds menu item matching this URL\n* Selected item and its ancestors marked with selected=true\n* Falls back to PrettyUrl mapping if direct match not found\n* Used for \"you are here\" navigation indicators\n* Example: \"/category/electronics/laptops/\"","schema":{"type":"string"}},{"name":"selected","in":"query","required":false,"description":"UUID of the explicitly selected menu item.\n\n* Directly specifies which item is currently active\n* Takes precedence over request_path\n* Selected item and ancestors marked with selected=true\n* Useful when URL doesn't directly map to menu structure","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successfully generated menu structure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MenuResponse"}}}},"400":{"description":"Validation error in request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["menus"]}}},"components":{"schemas":{"MenuResponse":{"type":"object","properties":{"menu":{"type":"array","items":{"$ref":"#/components/schemas/MenuItemDetail"},"description":"Array of menu items in the generated menu structure"}},"required":["menu"]},"MenuItemDetail":{"type":"object","properties":{"label":{"type":"string","description":"Display text for the menu item"},"url":{"type":"string","description":"Navigation URL (can be absolute or relative path)"},"level":{"type":"integer","description":"Depth level in the menu hierarchy (0-based, excluding root node)"},"pk":{"type":"string","format":"uuid","description":"Unique identifier for the menu item (UUID)"},"sort_order":{"type":"integer","description":"Ordering position within the same level (used for sorting siblings)"},"path":{"type":"string","description":"Materialized path for efficient tree traversal"},"parent_pk":{"type":"string","format":"uuid","nullable":true,"description":"Parent menu item's UUID (null for top-level items)"},"parent":{"type":"object","nullable":true,"description":"Parent menu item object (null for top-level items, populated by SetParentMenuModifier)"},"generator_name":{"type":"string","description":"Name of the generator that created this menu item"},"extra_context":{"type":"object","description":"Additional context data for the menu item","properties":{"attributes":{"type":"object","description":"Custom EAV attributes associated with this menu item","additionalProperties":true},"numchild":{"type":"integer","description":"Number of direct children under this menu item"}}},"selected":{"type":"boolean","description":"Indicates if this menu item is in the current navigation path (set by SetSelectedMenuModifier)"}},"required":["label","url","level","pk","sort_order","path","parent_pk","parent","generator_name","extra_context"]},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"object","description":"Validation errors keyed by field name","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Generate Breadcrumb

> This method generates a breadcrumb trail for the specified menu item, showing the path from the root to the current item.\
> \
> Breadcrumbs provide navigational context by displaying the hierarchy of pages leading to the current location. This endpoint traverses the menu tree from the specified item up to the root, creating a sequential trail of menu items.\
> \
> \*\*Breadcrumb Structure:\*\*\
> \* Items ordered from root to current (ascending hierarchy)\
> \* Each item includes full menu item details (label, url, level, etc.)\
> \* Parent relationships established between consecutive items\
> \* \`sort\_order\` reflects position in breadcrumb trail (0 = root)\
> \
> \*\*Use Cases:\*\*\
> \* Page breadcrumb navigation\
> \* SEO-friendly structured data (schema.org BreadcrumbList)\
> \* "You are here" indicators\
> \* Mobile navigation context\
> \* Accessibility navigation aids\
> \* Back-navigation helpers

```json
{"openapi":"3.0.3","info":{"title":"Menu API","version":"1.0.0"},"tags":[{"name":"menus","description":"Menu generation and breadcrumb navigation operations"}],"servers":[{"description":"Server base URL for basket operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/menus/generate_breadcrumb/":{"get":{"summary":"Generate Breadcrumb","description":"This method generates a breadcrumb trail for the specified menu item, showing the path from the root to the current item.\n\nBreadcrumbs provide navigational context by displaying the hierarchy of pages leading to the current location. This endpoint traverses the menu tree from the specified item up to the root, creating a sequential trail of menu items.\n\n**Breadcrumb Structure:**\n* Items ordered from root to current (ascending hierarchy)\n* Each item includes full menu item details (label, url, level, etc.)\n* Parent relationships established between consecutive items\n* `sort_order` reflects position in breadcrumb trail (0 = root)\n\n**Use Cases:**\n* Page breadcrumb navigation\n* SEO-friendly structured data (schema.org BreadcrumbList)\n* \"You are here\" indicators\n* Mobile navigation context\n* Accessibility navigation aids\n* Back-navigation helpers","operationId":"generate_breadcrumb","parameters":[{"name":"item","in":"query","required":true,"description":"UUID of the menu item to generate breadcrumb trail for.\n\n* Must be a valid UUID of an existing menu item\n* System retrieves this item and all its ancestors\n* Ancestors are items from root to this item (excluding root node)\n* If item not found, returns empty array\n* Example: \"550e8400-e29b-41d4-a716-446655440001\"","schema":{"type":"string","format":"uuid"}},{"name":"generator_name","in":"query","required":true,"description":"Name of the generator to use for breadcrumb generation.\n\n* Must match a registered generator in MENU_RENDERER_CONFIG\n* Default/standard generator: \"menu_item\" (MenuItemModelGenerator)\n* Generator must implement generate_breadcrumb_items method\n* Invalid generator name returns 400 validation error\n* Custom generators can be added for specialized breadcrumb logic","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully generated breadcrumb trail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MenuResponse"}}}},"400":{"description":"Validation error in request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["menus"]}}},"components":{"schemas":{"MenuResponse":{"type":"object","properties":{"menu":{"type":"array","items":{"$ref":"#/components/schemas/MenuItemDetail"},"description":"Array of menu items in the generated menu structure"}},"required":["menu"]},"MenuItemDetail":{"type":"object","properties":{"label":{"type":"string","description":"Display text for the menu item"},"url":{"type":"string","description":"Navigation URL (can be absolute or relative path)"},"level":{"type":"integer","description":"Depth level in the menu hierarchy (0-based, excluding root node)"},"pk":{"type":"string","format":"uuid","description":"Unique identifier for the menu item (UUID)"},"sort_order":{"type":"integer","description":"Ordering position within the same level (used for sorting siblings)"},"path":{"type":"string","description":"Materialized path for efficient tree traversal"},"parent_pk":{"type":"string","format":"uuid","nullable":true,"description":"Parent menu item's UUID (null for top-level items)"},"parent":{"type":"object","nullable":true,"description":"Parent menu item object (null for top-level items, populated by SetParentMenuModifier)"},"generator_name":{"type":"string","description":"Name of the generator that created this menu item"},"extra_context":{"type":"object","description":"Additional context data for the menu item","properties":{"attributes":{"type":"object","description":"Custom EAV attributes associated with this menu item","additionalProperties":true},"numchild":{"type":"integer","description":"Number of direct children under this menu item"}}},"selected":{"type":"boolean","description":"Indicates if this menu item is in the current navigation path (set by SetSelectedMenuModifier)"}},"required":["label","url","level","pk","sort_order","path","parent_pk","parent","generator_name","extra_context"]},"ErrorResponse":{"type":"object","properties":{"errors":{"type":"object","description":"Validation errors keyed by field name","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```