RateBack
RateBack allows users to send ratings to content providers using a URL included in a Web page or RSS feed. The user can rate content from their Web browser, RSS reader or MP3 player, and the ratings are sent back to the source, where they can be collected and shared with other users.
For example, musicsite provides a podcast feed with audio files. The user subscribes to the feed, and rates it while listening to it on an MP3 player. When the user synchronizes the MP3 player with their computer, the software sends a RateBack notification to musicsite. Using the ratings musicsite can make recommendations to other users of the most popular and highly rated files.
RateBack can be used with any content found on the Web and available through feeds, including Web pages, blog posts, video and software.
Design Principles
The RateBack API is designed around the following principles:
- Make it easy to add RateBack support to client applications and Web servers
- Make it easy to mix RateBack notifications from software and from Web-based user interfaces
- Allow rating of Web pages, part of Web pages, linked media files, feed items and feed enclosures
- RateBack notifications go back to the content provider
- RateBack is free to use
RateBack URLs
The RateBack URL specifies an endpoint for sending a rating notification about a single content item. By associating a RateBack URL with one content item, client applications only need to store that URL in order to send RateBack notifications. Servers can construct these URLs in any way, and clients MUST not depend on any particular format.
For example, musicsite uses the following RateBack URL to receive RateBack notifications for the song 'Happy Song':
http://musicsite/rateback/song/happy-song
RateBack Notifications
To send a RateBack notification, clients send an HTTP POST request to the RateBack URL using the content type application/x-www-form-urlencoded. The RateBack notification includes the following URL-encoded parameters:
- rating The rating is a value between 1 and 5, with 5 being the highest rating (5 out of 5). Alternatively, the rating may be a value on a scale between 1 and n, if the scale is specified explicitly, e.g. 6:10 indicates 6 out of 10.
- name Provides the user's name. This parameter is optional.
- email Provides the user's e-mail address. This parameter is optional.
- url Provides the user's URL (e.g. blog, home page). This parameter is optional.
- comment Short text to go along with the rating. This parameter is optional.
- agent Identifies the agent sending the RateBack notification. Application should use a URL, for example http://www.apple.com/itunes. This parameter is optional.
The client MUST provide a valid rating parameter. Servers MAY require other parameters, for example, to identify distinct users. All parameters MUST use the character encoding specified in the Content-Type header. There is no length restrictions on parameters, and servers MAY ignore or truncate any of these parameters.
For example, a RateBack notification might look like:
POST /rateback/song/happy-song HTTP/1.1 Host: musicsite User-Agent: MusicPlayer/1.0 Content-Type: application/x-www-form-urlencoded; charset=utf-8 rating=5&name=biggestfan&comment=best+song+ever
If the RateBack notification is successful, the server MUST respond in the following format:
<?xml version="1.0" encoding="utf-8"?> <rated> </rated>
In this version of the specification, the rated element has no element content (whitespaces are ignored). Future versions may provide more information by adding one or more sub-elements. Clients MUST not assume that the content of the rated element is always empty, but may discard the content if they are unable to interpret it.
If the RateBack notification fails, the server MUST respond in the following format:
<?xml version="1.0" encoding="utf-8"?> <error> <code>1</code> <message>An error occurred</message> </error>
If the server receives duplicate RateBack notifications, the server MUST respond successfully to each of the notifications.
Servers may use the same URL to provide a Web-based interface by which users can rate the content. The server is allowed to provide HTML content or redirect if it detects a HTTP GET request.
Auto Discovery
In HTML/XHTML content, RateBack URLs are identified from links that have the forward link type rateback.
For example:
<html>
<head>
<title>Short Stories</title>
<link rel="rateback" title="Rate these stories" href="http://example.com/rateback/short-stories"/>
</head>
...
</html>
or:
<h1>Today's Post</h1> . . . <p><a rel="rateback" href="http://example.com/rateback/todays-post"/>Rate this post</a></p>
Feeds may also use RateBack links embedded in the contents of a channel description or feed item. However, we recommend that feeds include the RateBack URL in the form of an extension. The extension uses the rateback element, defined in the namespace http://labnotes.org/rateback. The attribute url specifies the RateBack URL.
For example:
<rss version="2.0" xmlns:rb="http://labnotes.org/rateback">
...
<item>
<title>Happy Song</title>
...
<enclosure url="http://musicsite/mp3/song/happy-song.mp3" length="80000000" type="audio/mpeg"/>
<rb:rateback url="http://musicsite/rateback/song/happy-song"/>
</item>
</rss>
