Menus

Menu generation and breadcrumb navigation operations

Generate Menu

get

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

Query parameters

depth_heightinteger · min: 1Required

Number of levels to retrieve from the starting point.

Value of 1 retrieves only the immediate children
Value of 2 retrieves children and grandchildren
Combined with start_level to define the depth range
Example: start_level=0, depth_height=2 retrieves levels 0-1

Example: 2

parentstring · uuid · nullableOptional

UUID of the parent menu item to start generation from.

When provided, generates children of this parent
Overrides MENU_DEFAULT_PARENT_UUID setting
Cannot be used with sibling parameter
If parent not found, returns empty array
Null value allows root-level generation

Example: 550e8400-e29b-41d4-a716-446655440000

siblingstring · uuidOptional

UUID of a menu item to generate siblings for.

Generates items at the same level under the same parent
Useful for horizontal navigation or related sections
Cannot be used with parent parameter
If sibling not found, returns empty array

Example: 660e8400-e29b-41d4-a716-446655440001

start_levelintegerOptional

Starting depth level for menu generation (0-based, excluding root).

Default: 0 (top-level menu items)
Level 0 = first visible level
Level 1 = second level, and so on
Combined with depth_height to define range
If start_level > 0 and no parent determinable, returns empty array

Default: 0Example: 0

include_parentbooleanOptional

Whether to include the parent node in the results.

When true, parent item is added to the end of the array
Useful for breadcrumb trails or showing context
Only applies when parent parameter is specified
Parent must be visible (visible=true)

Default: falseExample: false

request_pathstringOptional

Current page URL path for context-aware menu highlighting.

System finds menu item matching this URL
Selected item and its ancestors marked with selected=true
Falls back to PrettyUrl mapping if direct match not found
Used for "you are here" navigation indicators
Example: "/category/electronics/laptops/"

Example: /category/electronics/laptops/

selectedstring · uuidOptional

UUID of the explicitly selected menu item.

Directly specifies which item is currently active
Takes precedence over request_path
Selected item and ancestors marked with selected=true
Useful when URL doesn't directly map to menu structure

Example: 770e8400-e29b-41d4-a716-446655440002

Responses

200

Successfully generated menu structure

application/json

400

Validation error in request parameters

application/json

get/menus/generate/

GET /menus/generate/?depth_height=2 HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

{
  "menu": [
    {
      "label": "Electronics",
      "url": "/category/electronics/",
      "level": 0,
      "pk": "550e8400-e29b-41d4-a716-446655440000",
      "sort_order": 0,
      "path": "00010001",
      "parent_pk": null,
      "parent": null,
      "generator_name": "menu_item",
      "extra_context": {
        "attributes": {
          "category_id": 123,
          "icon_class": "fa-laptop",
          "badge_text": "New"
        },
        "numchild": 5
      },
      "selected": true
    },
    {
      "label": "Laptops",
      "url": "/category/electronics/laptops/",
      "level": 1,
      "pk": "550e8400-e29b-41d4-a716-446655440001",
      "sort_order": 1,
      "path": "000100010001",
      "parent_pk": "550e8400-e29b-41d4-a716-446655440000",
      "parent": null,
      "generator_name": "menu_item",
      "extra_context": {
        "attributes": {
          "category_id": 124,
          "featured": true
        },
        "numchild": 3
      },
      "selected": true
    },
    {
      "label": "Smartphones",
      "url": "/category/electronics/smartphones/",
      "level": 1,
      "pk": "550e8400-e29b-41d4-a716-446655440002",
      "sort_order": 2,
      "path": "000100010002",
      "parent_pk": "550e8400-e29b-41d4-a716-446655440000",
      "parent": null,
      "generator_name": "menu_item",
      "extra_context": {
        "attributes": {
          "category_id": 125,
          "bestseller": true
        },
        "numchild": 2
      },
      "selected": false
    },
    {
      "label": "Headphones",
      "url": "/category/electronics/headphones/",
      "level": 1,
      "pk": "550e8400-e29b-41d4-a716-446655440003",
      "sort_order": 3,
      "path": "000100010003",
      "parent_pk": "550e8400-e29b-41d4-a716-446655440000",
      "parent": null,
      "generator_name": "menu_item",
      "extra_context": {
        "attributes": {
          "category_id": 126
        },
        "numchild": 4
      },
      "selected": false
    },
    {
      "label": "Clothing",
      "url": "/category/clothing/",
      "level": 0,
      "pk": "550e8400-e29b-41d4-a716-446655440010",
      "sort_order": 4,
      "path": "00010002",
      "parent_pk": null,
      "parent": null,
      "generator_name": "menu_item",
      "extra_context": {
        "attributes": {
          "category_id": 130,
          "seasonal": "winter"
        },
        "numchild": 6
      },
      "selected": false
    },
    {
      "label": "Men",
      "url": "/category/clothing/men/",
      "level": 1,
      "pk": "550e8400-e29b-41d4-a716-446655440011",
      "sort_order": 5,
      "path": "000100020001",
      "parent_pk": "550e8400-e29b-41d4-a716-446655440010",
      "parent": null,
      "generator_name": "menu_item",
      "extra_context": {
        "attributes": {
          "category_id": 131
        },
        "numchild": 4
      },
      "selected": false
    },
    {
      "label": "Women",
      "url": "/category/clothing/women/",
      "level": 1,
      "pk": "550e8400-e29b-41d4-a716-446655440012",
      "sort_order": 6,
      "path": "000100020002",
      "parent_pk": "550e8400-e29b-41d4-a716-446655440010",
      "parent": null,
      "generator_name": "menu_item",
      "extra_context": {
        "attributes": {
          "category_id": 132,
          "trending": true
        },
        "numchild": 5
      },
      "selected": false
    }
  ]
}

Generate Breadcrumb

get

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

Query parameters

itemstring · uuidRequired

UUID of the menu item to generate breadcrumb trail for.

Must be a valid UUID of an existing menu item
System retrieves this item and all its ancestors
Ancestors are items from root to this item (excluding root node)
If item not found, returns empty array
Example: "550e8400-e29b-41d4-a716-446655440001"

Example: 550e8400-e29b-41d4-a716-446655440001

generator_namestringRequired

Name of the generator to use for breadcrumb generation.

Must match a registered generator in MENU_RENDERER_CONFIG
Default/standard generator: "menu_item" (MenuItemModelGenerator)
Generator must implement generate_breadcrumb_items method
Invalid generator name returns 400 validation error
Custom generators can be added for specialized breadcrumb logic

Example: menu_item

Responses

200

Successfully generated breadcrumb trail

application/json

400

Validation error in request parameters

application/json

get/menus/generate_breadcrumb/

GET /menus/generate_breadcrumb/?item=550e8400-e29b-41d4-a716-446655440001&generator_name=menu_item HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

{
  "menu": [
    {
      "label": "Electronics",
      "url": "/category/electronics/",
      "level": 0,
      "pk": "550e8400-e29b-41d4-a716-446655440000",
      "sort_order": 0,
      "path": "00010001",
      "parent_pk": null,
      "parent": null,
      "generator_name": "menu_item",
      "extra_context": {
        "attributes": {
          "category_id": 123
        },
        "numchild": 5
      },
      "selected": false
    },
    {
      "label": "Laptops",
      "url": "/category/electronics/laptops/",
      "level": 1,
      "pk": "550e8400-e29b-41d4-a716-446655440001",
      "sort_order": 1,
      "path": "000100010001",
      "parent_pk": "550e8400-e29b-41d4-a716-446655440000",
      "parent": null,
      "generator_name": "menu_item",
      "extra_context": {
        "attributes": {
          "category_id": 124
        },
        "numchild": 3
      },
      "selected": false
    }
  ]
}

PreviousAdvanced Features NextModels

Last updated 8 months ago

Was this helpful?