[ventolin]

I've put together a small API (running on web.py) that stands in front of the traditional XBMC JSON-RPC API. The motivation is that I don't find the current API very developer-friendly, the documentation is chaotically organised and also not very developer-friendly, and I didn't find any javascript client libraries for the JSON-RPC API. (In addition to this, I'm not the best JS developer, and enjoy programming python far more).

The idea is to serve XBMC's data (and control functions) through a more RESTful interface. So, using proper resource endpoints, using HTTP methods appropriately, and so on.

All I've done so far are endpoints to expose the MusicLibrary. I'm posting this here to gauge interest, so I know whether it's worthwhile to continue development or not.

Here is one example, with traditional JSON-RPC API equivalents taken from http://wiki.xbmc.org/index.php?title=JSO...I/Examples :

Get the first 75 artists, sorted by artist (ascending) with extra fields

Traditional API, GET, params in URL

Code:

http://htpc:9999/jsonrpc?request=%7B%22jsonrpc%22%3A%20%222.0%22%2C%20%22method%22%3A%20%22AudioLibrary.GetArtists%22%2C%20%22params%22%3A%20%7B%20%22limits%22%3A%20%7B%20%22start%22%20%3A%200%2C%20%22end%22%3A%2075%20%7D%2C%20%22properties%22%3A%20%5B%20%22thumbnail%22%2C%20%22fanart%22%2C%20%22born%22%2C%20%22formed%22%2C%20%22died%22%2C%20%22disbanded%22%2C%20%22yearsactive%22%2C%20%22mood%22%2C%20%22style%22%2C%20%22genre%22%20%5D%2C%20%22sort%22%3A%20%7B%20%22order%22%3A%20%22ascending%22%2C%20%22method%22%3A%20%22artist%22%2C%20%22ignorearticle%22%3A%20true%20%7D%20%7D%2C%20%22id%22%3A%201%7D

Traditional API, POST, params in POST payload

Code:

http://htpc:9999/jsonrpc

Code:

{"jsonrpc": "2.0", "method": "AudioLibrary.GetArtists", "params": { "limits": { "start" : 0, "end": 75 }, "properties": [ "thumbnail", "fanart", "born", "formed", "died", "disbanded", "yearsactive", "mood", "style", "genre" ], "sort": { "order": "ascending", "method": "artist", "ignorearticle": true } }, "id": 1}

XBMC-REST, GET, params in URL

Code:

http://htpc:9999/music/artists?limit=75&sort=artist&fields=thumbnail,fanart,born,formed,died,disbanded,yearsactive,mood,style,genre

So. The first isn't really an option: totally unreadable, and the fact that URLs are capped makes it a bad choice. The second is a little better - however the entire object needs to be dumped to a jsonified string before being submitted, and the POST method is incorrect here (since we're GETting data, not modifying it). The third looks markedly more attractive, to me at least.

The code is here - https://github.com/kopf/script.service.restapi - please have a look around, and post your thoughts and comments here, as I'm apprehensive as to whether it's worthwhile to continue developing what would essentially be a "competing" API.

[Montellese]

IIRC there has been talk about implementing a RESTful API but it was discarded because maintaining two APIs and keeping them in sync is a lot of work and because there was nobody who had the time to even just do the RESTful API (without the work of keeping both APIs in sync).

I agree that JSON-RPC over HTTP is far from ideal but our JSON-RPC API is not limited to HTTP but also works through Python and (with even more features) over TCP and WebSockets.

I don't know much about RESTful except for the very basic principle so these questions may not be very accurate:

• Could it work over something else than HTTP?
  
• If yes, can it do server -> client communication (notifications)?
  
• How do you handle the more complex parameters like filters which can be recursive?
  

[Bstrdsmkr]

Server -> client stuff like notifications are usually handled through event subscription. For example, the client might call something like this:

Code:

http://htpc:9999/events/subscribe?event=onPlaybackStarted&callback_url=http%3A%2F%2F192.168.1.22%3A9998%2Fevent_handler%2Fon_playback_started

When the event of interest occurs, the server pulls on the (encoded) url provided in the callback_url param. Extended formats support tokens in the callback url which are replaced with url encoded data about the event

[Montellese]

Server -> client stuff like notifications are usually handled through event subscription. For example, the client might call something like this:

Code:

http://htpc:9999/events/subscribe?event=onPlaybackStarted&callback_url=http%3A%2F%2F192.168.1.22%3A9998%2Fevent_handler%2Fon_playback_started

When the event of interest occurs, the server pulls on the (encoded) url provided in the callback_url param. Extended formats support tokens in the callback url which are replaced with url encoded data about the event

So for this to work the client needs to run a "webserver" i.e. at least be able to listen on a TCP port and interpret the output as a HTTP request and send back a HTTP response.

[Bstrdsmkr]

For server back to client, yes that's the common pattern. In Python, that's a one or two line affair though. I suppose for local clients callback_URL could be a plugin:// URL too