iRATE XML-RPC Protocol v0.9.1

This page describes the XML-RPC protocol for iRATE, as it stands to be actually implemented. Comments, suggestions, and so on can be put on the XmlRpcComments page.

Info about migration : OldtoNewProtocolGateway

The examples of structures returned is given here in a Perl-like format.

URL and Authentication

The URL itself is server-dependent. To provide authentication information, we use HTTP auth (it's the XMLRPC default). The HTTP username should be the usual irate username and the password should be a hash generated by sha1( "irate" . sha1 ( $password ) ).

If the login/password is invalid, then an XML-RPC fault is generated.

Asking for new tracks

Request

Function: irate.getNew
Parameters:

• struct
  • n => number of tracks

n is of type int and specifies the number of tracks that are being requested, e.g. 6.

We give a struct here and not a simple int, because the client will be able to send an Accept: -like param, to ask for eg. only bittorrent sources, only oggs, etc...

Response

A struct is returned containing the tracks:

@newTracks = [{
        artistname => ...,
        trackname => ...,
        license => ...,
        albumname => ...,
        pubdate => ... (publishing date),
        mbid => ... (the musicbrainz ID of the track),
        duration => ... (milliseconds),
        Files => [{
                size => ...,
                sha1sum => ...,
                md5sum => ...,
                Sources => [{
                        crediturl => ...,
                        type => ..., # "url" or "bittorrent"
                        data1 => ..., # if type=url, the url. if type=bittorrent, the torrent's url.
                        data2 => .... # only used if type=bittorrent. the number of the file in case of multifile .torrent
                }, {
                        # repeat the above for multiple sources
                }]
        }, {
                # repeat for multiple files
        }]
}, {
        # repeat for multiple tracks
}];

The IDs used are www.musicbrainz.org one's. They're unique IDs, like 440fadf4-2761-434e-8746-a874af917c9f

(you can then go see http://musicbrainz.org/track/440fadf4-2761-434e-8746-a874af917c9f.html for info)

We discourage the use of files that aren't registered on musicbrainz, but it's still possible to use them with irate. In this case, the mbid will be a md5 of the url of the file (no musicbrainz id => unique file and unique source)

Rating Tracks

Request

Function: irate.rate
Parameters:

• Array containing the ratings (you can do multiple ratings in one call)

Each member of the array is a struct containing the info about the rating :

@rating = [{
        rating => ..., # integer type, (0-10)
        weight => ..., # double type, (0-1), defaults to 1
        mbid => ..., # musicbrainz ID of the file
}];

Response

The response from this may be discarded.

Unrating tracks

The unrate function has been removed. You can now just use irate.rate with a weight of 0 to unrate a track.

Getting track information

Request

Function: irate.getInfo
Parameters:

• array containing the structs id information on the track.

The array is in the same form as for irate.rate, except that the rating and weight fields should not be set.

Response

The response will be an array of structs with all the data the server knows about the track, the same as irate.getNew

Getting all the ratings back to the client

Request

Function: irate.getRatings
Parameters: none

Response

An array is returned in the following form:

@ratings = [{
        mbid => ...,
        rating => ...,
        weight => ...,
}, {
        # repeated for all the tracks the server knows about regarding this client
}];

Errors

Any errors are returned as XML-RPC faults. They contain an ID value and a human-readable message (which should be associated with an i18n string by the client). The numbers must start high as the lower values are reserved by XML-RPC itself.

Error codes :

• 801=> "??" (custom error)
• 802=>"MUST_LOGIN",
• 803=>"UNKNOWN_USER",
• 804=>"USER_NOT_ADMIN",
• 805=>"WRONG_PASSWORD",
• 806=>"USER_ALREADY_EXISTS",
• 807=>"REGISTERING_NOT_ALLOWED",
• 810=>"TRACK_NOT_FOUND",
• 811=>"RATING_MISSING",
• 812=>"BAD_INPUT"