View on GitHub

ickstream-docs

Public documentation about the ickStream Music Platform

Introduced in API version: 2.0

The getPreferredMenus method is used to retrieve information about preferred menus with references to request parameters which could be passed to the findItems method. The purpose of having a discovery protocol like this is to make it possible for a controller to check which menus that are preferred to show in a specific content service and apply it’s own user interface layout principles based on what’s preferred by the content service.

The menu structure returned by this method is not necessarily complete but only describes a top-level hierarchy. Where this hierarchy ends (has no more children) a controller shall use requests as specified by the preferredChildRequest field in the item returned by the lowest-level request. Where no such field is present (e.g. for playable items; streams or tracks) the controller has to rely on it’s own logic to create new lower-level menus.

Request:

{
    "jsonrpc": 2.0,
    "id": < A unique number used to correlate requests with responses, see JSON-RPC specification for more information >,
    "method": "getPreferredMenus",
    "params": {
        "offset": <Optional, numeric index of first item to retrieve >
        "count": <Optional, number of items to retrieve >
        "language": <Optional, language which is preferred, if not specified the default language will be used>
    }
}

Response:

{
    "jsonrpc": 2.0,
    "id": < The request identity >,
    "result": {
        "offset": <numeric index of the first item which is part of this response,
                          this is set based on the "offset" parameter provided in the request >
        "count": < number of items in this response, if "count" has been specified in request
                           it is the maximum value of this item >,
        "countAll": <total number of items available, ignoring any limitation specified with
                             offset and count request parameters>,
        "items": [
            { < First preferred menu >
                "type": < The type of menu, can contain values [search|browse] >
                "menuType": < The type of content which this menu contains >
                "text": < The user friendly name for this browse menu >
                "images": [ <Optional, array of images/logos available that should be used to represent this context>
                    {
                        "url": <URL to the image>
                        "type": <Type of image>
                        "width": <Width of image>
                        "height": <Height of image>
                    },
                    ...
                ],
                "childItems": [ < Optional, cannot be specified if childRequest is specified, contains static child items >
                    {
                        < First child item, same attribute as above >
                    }
                "childRequest": { <Optional, cannot be specified if childItems is specified, contains information about the request to issue to retrieve child items >
                    {
                        "request": < The unique identity of the request from the getProtocolDescription2 method, for example "myMusic:artists"
                        "childItems": [ < Optional, cannot be specified if childRequest is specified, contains static child items >
                        "childRequest": { <Optional, cannot be specified if childItems is specified, contains information about the request to issue to retrieve child items >
                    }
            },
            ...
        ]
    ]
}

A bit more detail:

Category:Content Access Protocol