API/Content Access Protocol

From ickStream Wiki
Revision as of 07:44, 18 July 2014 by Erland (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search



Each ickStream content service, local or ickStream Cloud, needs to offer a number of JSON-RPC commands for querying its data. Optionally they can also offer management function making it possible to add/remove items from a certain content in the content service.

Generic methods

Discovery methods

The purpose of these methods is to describe which query options a certain content service supports, this shall be used by a Controller to know what findItems, addItem and removeItem calls it can use.

Dynamic playlist methods

Query methods

  • findItems - Search or browse for content items
  • getItem - Get a specific content item

Streaming reference methods

myMusic context management methods

  • addItem - Add a content item to the myMusic context
  • removeItem - Remove a content item from the myMusic context

Resolving URI's

In the results from the Content Access Protocol there is a number of places where a URI is returned, the most common places are the *image* attribute in the main item and the *url* attribute inside the *streamingRefs* attribute.

The supported URL's are:

  • http/https urls
  • service url's with the syntax: service://<serviceId>/<path>\[?<queryParameters>\]\[#<fragment>\]
    • <serviceId> is the identity returned in [Cloud Core Protocol] methods findServices and findAllServices or the *id* returned from the *getServiceInformation* method in [Service Protocol] which all services have to implement.
    • <path>, <queryParameters> and <fragment> is the same as in any standard HTTP/HTTPS url

The service: URI's are mostly exposed from local content services but any ickStream device must ensure it can handle them both for local and cloud based content services.

The general principle is:

If a content service returns a URI like:

The ickStream device have to get the serviceURL attribute from the getServiceInformation method. Let's say getServiceInformation returns something like:

    "jsonrpc": "2.0",
    "id": "123",
    "result": {
        "id": "myUniqueServiceID",
        "name": "My Unique Service",
        "serviceURL": ""
To resolve the URL the ickStream device now have to replace the part
with the serviceURL attribute value so it ends up with a URL like:

Usage from a controller

See the creating a controller page for more details about how the method in this service it typically used by a controller.

The navigation of menu objects is a bit special:

  • Controller can navigate server side menus if type=menu
    • findItems type:menu
      • Gets the top level menu items where each item have
        • type=menu
        • id=<some id>
    • findItems menuId:<some id>
      • Will get the immediate child items below the menu item with id <some id>
    • findItems menuId:<some id> type:menu
      • Will get the immediate child items with type:menu below the menu item with id <some id>

There is no way to get a complete sub menu tree in a single request, the controller have to get one menu level at the time.

Examples of usage with artist/album/tracks based service

See the separate examples page

Personal tools