Programming API

MyTunesRSS comes with a programming API which lets you create your own frontend application in the programming language of your choice backed by the MyTunesRSS server. For complete new web interfaces the JSON-RPC API is probably your choice while for other clients the XML-RPC API might be the one to consider. Both APIs offer the exact same functions, so you whatever API you choose, you will not miss anything.

JSON-RPC API

JSON is a simple format mostly used in AJAX web applications for transferring data from server to client and vice versa. Using the JSON-RPC API is really simple. The following example assumes you have the MyTunesRSS server running and you can access it via http://localhost:8080, i.e. with default settings. All JSON-RPC calls have to be POST requests to the URL http://localhost:8080/jsonrpc with the content type application/json. The request body carries the call definition like in the following example.

{ 
    "version": "1.1", 
    "method": "AlbumService.getAlbums", 
    "id": "12345", 
    "params": [ 
        null,
        null,
        null,
        -1,
        0, 
        0 
    ]
}

The "version" and "id" do not matter. Both values will be returned as is in the response, so you can associate requests and responses in an asynchronous environment. The "method" specifies the API method and "params" is a list of method parameters. The API methods are explained in detail in the following chapters.

The remote API also supports the optional JSONP parameter. With a request paramater named "jsonp" you specify the function that should be calledin the response. The response will not be the JSON structure but a function call the to the specified function name with the JSON structure in the parameter. Please search the internet for more information on JSONP. Usually you will use such a call for cross-site-scripting by using it as the "src" attribute of a javascript block. In this case you will need a GET request and this is possible by specifying the data you would normally put in the POST body (as explained above) in a request parameter with the name "body".

XML-RPC API

The XML-RPC API is quite similar to the JSON-RPC API. In fact it offers exactly the same methods in XML. XML-RPC calls are POST requests to the URL http://localhost:8080/xmlrpc assuming the above mentioned preconditions. The request body carries the call details like in the following example. It is the same call as in the above JSON-RPC example.

<?xml version="1.0"?>
<methodCall>
    <methodName>AlbumService.getAlbums</methodName>
    <params>
      <param>
         <value/>
      </param>
      <param>
         <value/>
      </param>
      <param>
         <value/>
      </param>
      <param>
         <value><i4>-1</i4></value>
      </param>
      <param>
         <value><i4>0</i4></value>
      </param>
      <param>
         <value><i4>0</i4></value>
      </param>
    </params>
</methodCall>

Testing the API

Before actually starting to implement a MyTunesRSS application you probably want to play with the API a little to get used to it. The easiest way to do this is using the curl tool. It is a standard utility which should be available for your operating system.

You need to write simple text files with the request bodies, either in XML or JSON. Then call the curl utility with some parameters. The following examples show a call for JSON- and XML-RPC. The files test.json and test.xml contain the request body, i.e. something like the text in the above examples. You can try exactly these for getting started. Both calls are one line and split into multiple lines for readability purposes.

curl -H "Content-Type: application/json" \
        -d @test.json \
        http://localhost:8080/jsonrpc

curl -H "Content-Type: text/xml" \
        -d @test.xml \
        http://localhost:8080/xmlrpc

Most functions cannot be called without being authorized. You must authorize yourself with a valid MyTunesRSS user and password with the "LoginService.login" function. It is just like the web interface login. The following JSON code shows the call. The XML-RPC call is the same but in XML-RPC syntax. The parameters are the username, the password and the session timeout in seconds. After the specified time with no request the session will expire on the server.

{ 
    "version": "1.1", 
    "method": "LoginService.login", 
    "id": "12345", 
    "params": [ 
        "username",
        "password",
        10
    ]
}

After sending the above login command you will see a response with either a session ID string or an error in case the user could not be authorized. After a successful login you can send other commands (e.g. the album query above) using the session ID. The session ID must be specified in a request header (preferred method) with the name "X-MyTunesRSS-ID" or the request URL. Just append it to the service URL separated with a slash. So in case your session ID was "1234567890", you would send all subsequent calls to one of the following URLs.

http://localhost:8080/xmlrpc/1234567890
http://localhost:8080/jsonrpc/1234567890

Function overview

Click here for a function overview!

The JSON-RPC sample application

The JSON-RPC sample application can be run from anywhere on the same host that is running the MyTunesRSS server since it uses "localhost:8080" for connecting to the server. The sample application is iPhone optimized (converning the layout) but works on any other browser as well of course.

© 2010 Codewave Software - Michael Descher