View source for API/Content Access Protocol

= 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 = 
* [[API/Service Protocol/getServiceInformation|getServiceInformation]] - Get information about service
* [[API/Service Protocol/getProtocolVersions|getProtocolVersions]] - Get information about supported protocol versions
* [[API/Content Access Protocol/getAccountInformation|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.
* <strike>[[API/Content Access Protocol/getProtocolDescription|getProtocolDescription]]</strike> - Get information about available queries that can be used in [[API/Content Access Protocol/findItems|findItems]] method
* [[API/Content Access Protocol/getProtocolDescription2|getProtocolDescription2]] - Get information about available queries that can be used in [[API/Content Access Protocol/findItems|findItems]] method
* [[API/Content Access Protocol/getPreferredMenus|getPreferredMenus]] - Get information about preferred menus which is appropriate to render for this service
* [[API/Content Access Protocol/getManagementProtocolDescription|getManagementProtocolDescription]] - Get information about available possibilities that are available for [[API/Content Access Protocol/addItem|addItem]] and [[API/Content Access Protocol/removeItem|removeItem]] methods.

= Dynamic playlist methods =
* [[API/Content Access Protocol/getNextDynamicPlaylistTracks|getNextDynamicPlaylistTracks]] - Retrieve next tracks for a dynamic playlist

= Query methods =
* [[API/Content Access Protocol/findItems|findItems]] - Search or browse for content items
* [[API/Content Access Protocol/getItem|getItem]] - Get a specific content item

= Streaming reference methods =
* [[API/Content Access Protocol/getItemStreamingRef|getItemStreamingRef]] - Get streaming reference for a specific track/stream

= myMusic context management methods =

* [[API/Content Access Protocol/addItem|addItem]] - Add a content item to the myMusic context
* [[API/Content Access Protocol/removeItem|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: <pre>service://myUniqueServiceID/album1/track1.flac</pre>

The ickStream device have to get the '''serviceURL''' attribute from the [[API/Service  Protocol/getServiceInformation|getServiceInformation]] method. Let's say [[API/Service Protocol/getServiceInformation|getServiceInformation]] returns something like:
<syntaxhighlight lang="javascript">{
    "jsonrpc": "2.0",
    "id": "123",
    "result": {
        "id": "myUniqueServiceID",
        "name": "My Unique Service",
        "serviceURL": "http://192.168.0.33/myuniqueapplication"
    }
}
</syntaxhighlight>

To resolve the URL the ickStream device now have to replace the part <pre>service://myUniqueServiceID</pre> with the '''serviceURL''' attribute value so it ends up with a URL like:
<pre>http://192.168.0.33/myuniqueapplication/album1/track1.flac</pre>

= Usage from a controller =

See the [[API/Creating_a_controller|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 [[API/Content Access Protocol Examples|the separate examples page]]

[[Category:API]]