Developers

Welcome to the Twones Developer section. We are currently developing an API for Twones functions and tracking services. At the moment, developers can interact with Twones through two channels: our Read API and Toolbar API. We want to welcome all to support us in developing Twones. Take a look at our » Twones Development Base for API/dev related inquiries. Basically there's allways something we can use your help on.

(In this document we will constantly use Twones founder Tim, username 'theineke' as an example.)

TWONES READ API

What we call our Read API is a set of urls that accept GET requests and do not require authentication. As the name suggests this is the way to go if you wanna get information OUT of Twones.

All these urls follow the same general law: Append the named parameter 'format' to the URL.

Tim's favorites:

http://twones.com/theineke/favorites

Tim's favorites in xspf:

http://twones.com/theineke/favorites/format:xspf

(We follow cakephp's standard named parameters format.)

Currently this parameter only accepts XSPF. You can learn more about XSPF on » this page. Roughly XSPF is a playlist in XML. The idea was that every information that Twones shares with the web would be easily playable. But since on Twones we have more information about the track (times tracked, who played, etc.) we stressed the XSPF format a little bit. We'll talk about how we've extended this later.

First, let's list the urls:

Popular tracks today:

http://twones.com/popular/today/format:xspf

Popular tracks this week:

http://twones.com/popular/this_week/format:xspf

Popular tracks all time:

http://twones.com/popular/all_time/format:xspf

Tim's activities (all):

http://twones.com/theineke/timeline/collection:solo/format:xspf

What Tim played:

http://twones.com/theineke/timeline/collection:solo/target:plays/format:xsp

Which tracks Tim favorited:

http://twones.com/theineke/timeline/collection:solo/target:favorites/format:xspf

Tim's favorites:

http://twones.com/theineke/favorites/format:xspf

Tim has a playlist called "wave". Its ID is 201:

http://twones.com/theineke/favorites/playlists/201/format:xspf

Tim's friends activities:

http://twones.com/theineke/timeline/collection:friends/format:xspf

What Tim's friends are listening:

http://twones.com/theineke/timeline/collection:friends/target:plays/format:xspf

What Tim's friends are listening:

http://twones.com/theineke/timeline/collection:friends/target:plays/format:xspf

Everybody's activities:

http://twones.com/theineke/timeline/collection:public/format:xspf

What is everybody listening:

http://twones.com/theineke/timeline/collection:public/target:plays/format:xspf

Lets say I wanna know what just played in UNIX time 20090814094930 on the internet. I use the offset parameter:

http://twones.com/timeline/collection:public/target:plays/offset:20090814094930/format:xspf

Lets say I wanna know the last 5 played tracks. I use the counter parameter:

http://twones.com/timeline/collection:public/target:plays/counter:5/format:xspf

Lets say I wanna know from the 5th to the 10th tracks. I use the counter and number parameters:

http://twones.com/timeline/collection:public/target:all/number:5/counter:10/format:xspf

XSPF extensions

As mentioned before we extended the XSPF format to cope with our needs. We tried not to break it though...
Here its a list of them:

A link that when you visit you can play the track:

<link rel="http://twones.com/ns/jspf#playLink">http://hypem.com/882622/Nude+(HIPSTER+RUNOFF+REMIX)</link>

Where the track was listened:

<link rel="http://twones.com/ns/jspf#pageLink">http://hypem.com/popular</link>

An internal link to the service icon:

<meta rel="http://twones.com/ns/jspf#metaServiceIcon">/img/Service/hypem.png</meta>

The service name:

<meta rel="http://twones.com/ns/jspf#metaService">hypem</meta>

A link to the service:

<link rel="http://twones.com/ns/jspf#metaService">http://hypem.com</link>

The user that performed the activity:

<meta rel="http://twones.com/ns/jspf#user">theineke</meta>

The original user if this is a replay event:

<meta rel="http://twones.com/ns/jspf#replayFromUser">diederik</meta>

The event type (play or favorite):

<meta rel="http://twones.com/ns/jspf#eventType">play</meta>