API/Content Access Protocol
Contents |
Principles
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
- getServiceInformation - Get information about service
- getProtocolVersions - Get information about supported protocol versions
- getAccountInformation - Get information about the account the user is using in the service
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.
-
getProtocolDescription- Get information about available queries that can be used in findItems method - getProtocolDescription2 - Get information about available queries that can be used in findItems method
- getPreferredMenus - Get information about preferred menus which is appropriate to render for this service
- getManagementProtocolDescription - Get information about available possibilities that are available for addItem and removeItem methods.
Dynamic playlist methods
- getNextDynamicPlaylistTracks - Retrieve next tracks for a dynamic playlist
Query methods
Streaming reference methods
- getItemStreamingRef - Get streaming reference for a specific track/stream
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:
service://myUniqueServiceID/album1/track1.flac
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": "http://192.168.0.33/myuniqueapplication" } }
service://myUniqueServiceIDwith the serviceURL attribute value so it ends up with a URL like:
http://192.168.0.33/myuniqueapplication/album1/track1.flac
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>
- Gets the top level menu items where each item have
- 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>
- findItems type:menu
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.