MP3tunes Oboe API Documentation

Table of Contents

1. Overview
Overview
Technical Contacts
Request and Response formats
Servers
2. Oboe Locker Streaming API
Overview
Authentication
login
accountData
Organization
lockerData
Streaming
lockerGet
3. Oboe Locker Syncing API
Overview
Authentication
login
accountData
A. Response Headers

List of Examples

1.1. REST Request
1.2. Response without debug parameter
1.3. Response with debug parameter
2.1. Successful authentication response (JSON)
2.2. Successful authentication response (XML)
2.3. Unsuccessful authentication response (JSON)
2.4. Unsuccessful authentication response (XML)
2.5. Successful accountData response (JSON)
2.6. Successful accountData response (XML)
2.7. Unsuccessful accountData response (JSON)
2.8. Unsuccessful accountData response (XML)
2.9. Listing albums in a user's locker (JSON)
2.10. Listing albums in a user's locker (XML)
2.11. Listing the tracks in an album (JSON)
2.12. Listing the tracks in an album (XML)
2.13. Listing the playlists in a user's locker (XML)
3.1. Successful authentication response (JSON)
3.2. Successful authentication response (XML)
3.3. Unsuccessful authentication response (JSON)
3.4. Unsuccessful authentication response (XML)
3.5. Successful accountData response (JSON)
3.6. Successful accountData response (XML)
3.7. Unsuccessful accountData response (JSON)
3.8. Unsuccessful accountData response (XML)

Chapter 1. Overview

Table of Contents

Overview
Technical Contacts
Request and Response formats
Servers

Overview

The MP3tunes Oboe API consists mainly of an easy to use REST interface which gives you access to all functionality of the MP3tunes Locker service. With this API you can do everything from writing a quick Perl script to fill your own MP3tunes Locker with media to writing a full sync client for your favorite portable device.

This document has a strong focus on two types of applications; those used for streaming, and those used for syncing. This means that the majority of this document is split into those two sections, respectively.

Technical Contacts

  • Doug Reese <dougr@mp3tunes.com> (Primary technical contact)

  • Cody Brocious <cody@mp3tunes.com>

  • Derek Ford <derek@mp3tunes.com>

  • Jon Johansen <jon@mp3tunes.com>

Request and Response formats

Request format.  Currently only REST requests are supported.

Example 1.1. REST Request


     http://www.mp3tunes.com/api/v0/<method>?<params>

Response formats.  Currently JSON and XML response formats are supported. You may choose the response format by passing the "output" parameter with a value of either "xml" or "json". If no output parameter is passed the response defaults to JSON.

The output can be decoded into a more readable format by adding a "debug=1" parameter to any request. This will cause the formatted output to be reinterpreted and displayed as a native type in a readable format -- especially useful in interpreting JSON output. The use of the "debug=1" parameter is highly encouraged, as opposed to detailed documentation describing the output of the API requests. The API is still evolving, and it cannot be guaranteed that such detailed documentation will be continuously updated.

Example 1.2. Response without debug parameter 


https://shop.mp3tunes.com/api/v0/login

{"status":0,"session_id":null,"errorMessage":"The provided email address is not properly formatted"}

Example 1.3. Response with debug parameter


https://shop.mp3tunes.com/api/v0/login?debug=1

{"status":0,"session_id":null,"errorMessage":"The provided email address is not properly formatted"}
object(ObjectFromJSON)#7 (3) { ["status"]=> int(0) ["session_id"]=> NULL ["errorMessage"]=> string(52) "The provided email address is not properly formatted" }

Servers

The MP3tunes Oboe service has a set of servers dedicated to specific tasks, and it is important that when using the API you use the correct servers for specific types of requests. These servers are separated by mp3tunes.com subdomains. Each request method's documentation will list the correct subdomain to use for that method. Currently there are three subdomains, and respectively three types of requests.

Servers

Authentication API methods

API methods which deal with authentication (SSL) use the https://shop.mp3tunes.com/ domain.

General API methods

General API methods use the http://ws.mp3tunes.com/ domain.

Storage API methods

Storage API methods use the http://content.mp3tunes.com/ domain.

Chapter 2. Oboe Locker Streaming API

Table of Contents

Overview
Authentication
login
accountData
Organization
lockerData
Streaming
lockerGet

Overview

This section focuses on the portions of the API which are used for streaming MP3tunes lockers. The process used to stream music from an MP3tunes locker contains the following steps:

  • Authentication; Logging in and receiving a session id, retrieving account data.

  • Organization; Building a list of songs to stream, specifying stream options.

  • Streaming; Retrieving songs and playlists from a users' Locker.

Authentication

Authentication allows the server to generate a session for the user. Without a session you will not be able to stream, or collect data about a user account.

login

https://shop.mp3tunes.com/api/v0/login?username=<username>&password=<password>&partner_token=<partner token>&output=<output format>

parameters

partner_token (required)

A Partner Token is used to uniquely identify and authenticate all entities using API's to communicate with MP3tunes.com. If you do not already have a partner token you may request one from the partner page.

username (required)

A valid MP3tunes account username. LINK TO SECTION COVERING ACCOUNT CREATION API CALLS HERE

password (required)

A valid MP3tunes account password. LINK TO SECTION COVERING ACCOUNT CREATION API CALLS HERE

output (optional)

Your preferred output format. These include xml, and json.

The login method attempts to authenticate the received user credentials and setup a session to be used with all subsequent requests. On success the 'status' parameter is set to 1, and a valid session id is returned. If authentication fails the 'status' parameter is set to 0, and the 'errorMessage' parameter is populated with appropriate error messages detailing what caused the call to fail.

Example 2.1. Successful authentication response (JSON)


https://shop.mp3tunes.com/api/v0/login?username=apitest@example.com&password=apitestpassword&partner_token=XXXXXXXXXX&output=json

{"status":1,
 "session_id":"ec08029c87e05b2c49b6ac0cd194b68b",
 "username":"apitest@example.com",
 "errorMessage":null}

Example 2.2. Successful authentication response (XML)


https://shop.mp3tunes.com/api/v0/login?username=apitest@example.com&password=apitestpassword&partner_token=XXXXXXXXXX&output=xml

<mp3tunes>
 <status>1</status>
 <session_id>ec08029c87e05b2c49b6ac0cd194b68b</session_id>
 <username>apitest@example.com</username>
 <errorMessage/>
</mp3tunes>

Example 2.3. Unsuccessful authentication response (JSON)


https://shop.mp3tunes.com/api/v0/login?username=apitest@example.com&password=apitestpassword&partner_token=invalidtoken&output=json

{"status":0,
 "errorMessage":"The partner_token input parameter failed validation."}

Example 2.4. Unsuccessful authentication response (XML)


https://shop.mp3tunes.com/api/v0/login?username=apitest@example.com&password=apitestpassword&partner_token=invalidtoken&output=xml

<mp3tunes>
 <status>0</status>
 <errorMessage>
  The partner_token input parameter failed validation.
 </errorMessage>
</mp3tunes>

accountData

http://ws.mp3tunes.com/api/v0/accountData?sid=<session id>&partner_token=<partner token>&output=<output format>

parameters

sid (required)

A valid session id, received from the “login” method.

partner_token (required)

A valid partner token. A Partner Token is used to uniquely identify and authenticate all entities using API's to communicate with MP3tunes.com. If you do not already have a partner token you may request one from the partner page.

output (optional)

Your preferred output format. These include xml, and json.

The accountData method retrieves information about a user account. This method will tell you what subscription level a user account has as well as the users' email address, name, and nickname.

Example 2.5. Successful accountData response (JSON)


http://ws.mp3tunes.com/api/v0/accountData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=json

{"user": {"email":"apitest@example.com",
          "nickName":null,
          "firstName":"Robert",
          "lastName":"Paulson",
          "subscriptions": [{"name":"user_locker_annual",
                             "description":"Locker Account - Annual"}]}}

Example 2.6. Successful accountData response (XML)


http://ws.mp3tunes.com/api/v0/accountData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=xml

<mp3tunes>
 <user>
  <email>apitest@example.com</email>
  <nickName/>
  <firstName>Robert</firstName>
  <lastName>Paulson</lastName>
  <subscriptions>
   <item>
    <name>user_locker_annual</name>
    <description>Locker Account - Annual</description>
   </item>
  </subscriptions>
 </user>
</mp3tunes>

Example 2.7. Unsuccessful accountData response (JSON)


http://ws.mp3tunes.com/api/v0/accountData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=json

{"status":0,
 "errorMessage":"Not logged in"}

Example 2.8. Unsuccessful accountData response (XML)


http://ws.mp3tunes.com/api/v0/accountData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=xml

<mp3tunes>
 <status>0</status>
 <errorMessage>Not logged in</errorMessage>
</mp3tunes>

Organization

The organization related methods allow you to specify streaming options as well as build a list of files to stream.

lockerData

http://ws.mp3tunes.com/api/v0/lockerData?sid=<session id>&partner_token=<partner token>&output=<output format>

parameters

sid (required)

A valid session id, received from the “login” method.

partner_token (required)

A valid partner token. A Partner Token is used to uniquely identify and authenticate all entities using API's to communicate with MP3tunes.com. If you do not already have a partner token you may request one from the partner page.

output (optional)

Your preferred output format. These include xml, and json.

type (optional)

Type options constist of artist, album, track, and playlist. Passing a type of artist, album, or playlist will return the respective id's of those types of content in a user's locker.

album_id (optional)

Id of an album in a user's locker. A list of albums in a user's locker can be retrieved by passing a type of album.

artist_id (optional)

Id of an artist in a user's locker. A list of artists in a user's locker can be retrieved by passing a type of artist.

The lockerData method allows you to retrieve a list of the contents of a user's locker. You can retrieve a list of every track in a locker, or compile a list of only artists, albums, or playlists. You use the track type to list all of the tracks in a user's locker. In order to list only the tracks by a specific artist or in a specific album you use the track type in conjunction with the artist_id and album_id parameters.

Example 2.9. Listing albums in a user's locker (JSON)


http://ws.mp3tunes.com/api/v0/lockerData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=json&type=album

[{"albumId":"160",
  "albumTitle":"...In All Their Splendor",
  "artistId":"130","artistName":"Li'l Cap'n Travis"},
 {"albumId":"406",
  "albumTitle":"..aspen it is",
  "artistId":"301",
  "artistName":"..aspenitis"},
 {"albumId":"13",
  "albumTitle":"10 Horse Johnson",
  "artistId":"11",
  "artistName":"10 Horse Johnson"},
 {"albumId":"902",
  "albumTitle":"Scenes From A Memory",
  "artistId":"25",
  "artistName":"Dream Theater"}]

Example 2.10. Listing albums in a user's locker (XML)


http://ws.mp3tunes.com/api/v0/lockerData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=xml&type=album

<mp3tunes>
 <item>
  <albumId>160</albumId>
  <albumTitle>...In All Their Splendor</albumTitle>
  <artistId>130</artistId>
  <artistName>Li'l Cap'n Travis</artistName>
 </item>
 <item>
  <albumId>406</albumId>
  <albumTitle>..aspen it is</albumTitle>
  <artistId>301</artistId>
  <artistName>..aspenitis</artistName>
 </item>
 <item>
  <albumId>13</albumId>
  <albumTitle>10 Horse Johnson</albumTitle>
  <artistId>11</artistId>
  <artistName>10 Horse Johnson</artistName>
 </item>
 <item>
  <albumId>902</albumId>
  <albumTitle>Scenes From A Memory</albumTitle>
  <artistId>25</artistId>
  <artistName>Dream Theater</artistName>
 </item>
</mp3tunes>

Example 2.11. Listing the tracks in an album (JSON)


http://ws.mp3tunes.com/api/v0/lockerData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=json&type=track&album_id=902

{"albumData": {"albumId":"902",
               "albumTitle":"Scenes From A Memory",
               "artistId":"25",
               "artistName":"Dream Theater"},
 "trackList":[{"trackId":"12022",
               "trackTitle":"Scene One - Regression",
               "trackNumber":"1",
               "trackLength":126754.062500,
               "trackFileName":"scene_one__regression.mp3",
               "trackFileKey":"456e7d07e3857455eca4afdee8d8598e",
               "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/456e7d07e3857455eca4afdee8d8598e?sid=ec08029c87e05b2c49b6ac0cd194b68b",
               "albumTitle":"Scenes From A Memory",
               "albumYear":"1999",
               "artistName":"Dream Theater"},
              {"trackId":"12024",
               "trackTitle":"Scene Two - I. Overture 1928",
               "trackNumber":"2",
               "trackLength":217921.375000,
               "trackFileName":"scene_two__i_overture_1928.mp3",
               "trackFileKey":"1f57736f02048243db0d43c0ded5120d",
               "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/1f57736f02048243db0d43c0ded5120d?sid=ec08029c87e05b2c49b6ac0cd194b68b",
               "albumTitle":"Scenes From A Memory",
               "albumYear":"1999",
               "artistName":"Dream Theater"},
              {"trackId":"12026",
               "trackTitle":"Scene Two - II. Strange Deja Vu",
               "trackNumber":"3",
               "trackLength":312458.500000,
               "trackFileName":"scene_two__ii_strange_deja_vu.mp3",
               "trackFileKey":"6cdb0b8e97ed7fc658fbcd2a2745d6a9",
               "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/6cdb0b8e97ed7fc658fbcd2a2745d6a9?sid=ec08029c87e05b2c49b6ac0cd194b68b",
               "albumTitle":"Scenes From A Memory",
               "albumYear":"1999",
               "artistName":"Dream Theater"},
              {"trackId":"12025",
               "trackTitle":"Scene Three - I. Through My Words",
               "trackNumber":"4",
               "trackLength":62257.687500,
               "trackFileName":"scene_three__i_through_my_words.mp3",
               "trackFileKey":"5d84aaee5af711ff06f4ecdadcfb0c12",
               "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/5d84aaee5af711ff06f4ecdadcfb0c12?sid=ec08029c87e05b2c49b6ac0cd194b68b",
               "albumTitle":"Scenes From A Memory",
               "albumYear":"1999",
               "artistName":"Dream Theater"},
              {"trackId":"12028",
               "trackTitle":"Scene Three - II. Fatal Tragedy",
               "trackNumber":"5",
               "trackLength":409477.312500,
               "trackFileName":"scene_three__ii_fatal_tragedy.mp3",
               "trackFileKey":"2d8bcf3bdc75d33eca151b1ef74b3233",
               "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/2d8bcf3bdc75d33eca151b1ef74b3233?sid=ec08029c87e05b2c49b6ac0cd194b68b",
               "albumTitle":"Scenes From A Memory",
               "albumYear":"1999",
               "artistName":"Dream Theater"},
              {"trackId":"12029",
               "trackTitle":"Scene Four - Beyond This Life",
               "trackNumber":"6",
               "trackLength":682770.375000,
               "trackFileName":"scene_four__beyond_this_life.mp3",
               "trackFileKey":"5b00f8e121eec87cdeaa85b7159246d0",
               "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/5b00f8e121eec87cdeaa85b7159246d0?sid=ec08029c87e05b2c49b6ac0cd194b68b",
               "albumTitle":"Scenes From A Memory",
               "albumYear":"1999",
               "artistName":"Dream Theater"},
              {"trackId":"12023",
               "trackTitle":"Scene Five - Through Her Eyes",
               "trackNumber":"7",
               "trackLength":329359.750000,
               "trackFileName":"scene_five__through_her_eyes.mp3",
               "trackFileKey":"2c9506ddbb374d47793d3ce07ee48443",
               "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/2c9506ddbb374d47793d3ce07ee48443?sid=ec08029c87e05b2c49b6ac0cd194b68b",
               "albumTitle":"Scenes From A Memory",
               "albumYear":"1999",
               "artistName":"Dream Theater"},
              {"trackId":"12030",
                "trackTitle":"Scene Six - Home",
                "trackNumber":"8",
                "trackLength":773467.500000,
                "trackFileName":"scene_six__home.mp3",
                "trackFileKey":"af1d1a9e4f3d9caba4bba859a35fd396",
                "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/af1d1a9e4f3d9caba4bba859a35fd396?sid=ec08029c87e05b2c49b6ac0cd194b68b",
                "albumYear":"1999",
                "artistName":"Dream Theater"},
               {"trackId":"12033",
                "trackTitle":"Scene Seven - I. The Dance Of Eternity",
                "trackNumber":"9",
                "trackLength":373767.937500,
                "trackFileName":"scene_seven__i_the_dance_of_eternity.mp3",
                "trackFileKey":"9eaffc87815d17eb100b42648a7c089b",
                "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/9eaffc87815d17eb100b42648a7c089b?sid=ec08029c87e05b2c49b6ac0cd194b68b",
                "albumTitle":"Scenes From A Memory",
                "albumYear":"1999",
                "artistName":"Dream Theater"},
               {"trackId":"12031",
                "trackTitle":"Scene Seven - II. One Last Time",
                "trackNumber":"10",
                "trackLength":226829.125000,
                "trackFileName":"scene_seven__ii_one_last_time.mp3",
                "trackFileKey":"912585cfbf3319693118c347935da726",
                "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/912585cfbf3319693118c347935da726?sid=ec08029c87e05b2c49b6ac0cd194b68b",
                "albumTitle":"Scenes From A Memory",
                "albumYear":"1999",
                "artistName":"Dream Theater"},
               {"trackId":"12032",
                "trackTitle":"Scene Eight - The Spirit Carries On",
                "trackNumber":"11",
                "trackLength":398349.125000,
                "trackFileName":"scene_eight__the_spirit_carries_on.mp3",
                "trackFileKey":"6722e70adaf9291552db559f41506a07",
                "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/6722e70adaf9291552db559f41506a07?sid=ec08029c87e05b2c49b6ac0cd194b68b",
                "albumTitle":"Scenes From A Memory",
                "albumYear":"1999",
                "artistName":"Dream Theater"},
               {"trackId":"12034",
                "trackTitle":"Scene Nine - Finally Free",
                "trackNumber":"12",
                "trackLength":719864.250000,
                "trackFileName":"scene_nine__finally_free.mp3",
                "trackFileKey":"57b4ce3a89b5c02c8b119f11faf1ba03",
                "downloadURL":"http:\/\/content.mp3tunes.com\/storage\/lockerget\/57b4ce3a89b5c02c8b119f11faf1ba03?sid=ec08029c87e05b2c49b6ac0cd194b68b",
                "albumTitle":"Scenes From A Memory",
                "albumYear":"1999",
                "artistName":"Dream Theater"}]}

Example 2.12. Listing the tracks in an album (XML)


http://ws.mp3tunes.com/api/v0/lockerData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=xml&type=track&album_id=902

<mp3tunes>
 <albumData>
  <albumId>902</albumId>
  <albumTitle>Scenes From A Memory</albumTitle>
  <artistId>25</artistId>
  <artistName>Dream Theater</artistName>
 </albumData>
 <trackList>
  <item>
   <trackId>12022</trackId>
   <trackTitle>Scene One - Regression</trackTitle>
   <trackNumber>1</trackNumber>
   <trackLength>126754.0625</trackLength>
   <trackFileName>scene_one__regression.mp3</trackFileName>
   <trackFileKey>456e7d07e3857455eca4afdee8d8598e</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/456e7d07e3857455eca4afdee8d8598e?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12024</trackId>
   <trackTitle>Scene Two - I. Overture 1928</trackTitle>
   <trackNumber>2</trackNumber>
   <trackLength>217921.375</trackLength>
   <trackFileName>scene_two__i_overture_1928.mp3</trackFileName>
   <trackFileKey>1f57736f02048243db0d43c0ded5120d</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/1f57736f02048243db0d43c0ded5120d?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12026</trackId>
   <trackTitle>Scene Two - II. Strange Deja Vu</trackTitle>
   <trackNumber>3</trackNumber>
   <trackLength>312458.5</trackLength>
   <trackFileName>scene_two__ii_strange_deja_vu.mp3</trackFileName>
   <trackFileKey>6cdb0b8e97ed7fc658fbcd2a2745d6a9</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/6cdb0b8e97ed7fc658fbcd2a2745d6a9?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12025</trackId>
   <trackTitle>Scene Three - I. Through My Words</trackTitle>
   <trackNumber>4</trackNumber>
   <trackLength>62257.6875</trackLength>
   <trackFileName>scene_three__i_through_my_words.mp3</trackFileName>
   <trackFileKey>5d84aaee5af711ff06f4ecdadcfb0c12</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/5d84aaee5af711ff06f4ecdadcfb0c12?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12028</trackId>
   <trackTitle>Scene Three - II. Fatal Tragedy</trackTitle>
   <trackNumber>5</trackNumber>
   <trackLength>409477.3125</trackLength>
   <trackFileName>scene_three__ii_fatal_tragedy.mp3</trackFileName>
   <trackFileKey>2d8bcf3bdc75d33eca151b1ef74b3233</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/2d8bcf3bdc75d33eca151b1ef74b3233?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12029</trackId>
   <trackTitle>Scene Four - Beyond This Life</trackTitle>
   <trackNumber>6</trackNumber>
   <trackLength>682770.375</trackLength>
   <trackFileName>scene_four__beyond_this_life.mp3</trackFileName>
   <trackFileKey>5b00f8e121eec87cdeaa85b7159246d0</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/5b00f8e121eec87cdeaa85b7159246d0?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12023</trackId>
   <trackTitle>Scene Five - Through Her Eyes</trackTitle>
   <trackNumber>7</trackNumber>
   <trackLength>329359.75</trackLength>
   <trackFileName>scene_five__through_her_eyes.mp3</trackFileName>
   <trackFileKey>2c9506ddbb374d47793d3ce07ee48443</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/2c9506ddbb374d47793d3ce07ee48443?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12030</trackId>
   <trackTitle>Scene Six - Home</trackTitle>
   <trackNumber>8</trackNumber>
   <trackLength>773467.5</trackLength>
   <trackFileName>scene_six__home.mp3</trackFileName>
   <trackFileKey>af1d1a9e4f3d9caba4bba859a35fd396</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/af1d1a9e4f3d9caba4bba859a35fd396?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12033</trackId>
   <trackTitle>Scene Seven - I. The Dance Of Eternity</trackTitle>
   <trackNumber>9</trackNumber>
   <trackLength>373767.9375</trackLength>
   <trackFileName>scene_seven__i_the_dance_of_eternity.mp3</trackFileName>
   <trackFileKey>9eaffc87815d17eb100b42648a7c089b</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/9eaffc87815d17eb100b42648a7c089b?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12031</trackId>
   <trackTitle>Scene Seven - II. One Last Time</trackTitle>
   <trackNumber>10</trackNumber>
   <trackLength>226829.125</trackLength>
   <trackFileName>scene_seven__ii_one_last_time.mp3</trackFileName>
   <trackFileKey>912585cfbf3319693118c347935da726</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/912585cfbf3319693118c347935da726?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12032</trackId>
   <trackTitle>Scene Eight - The Spirit Carries On</trackTitle>
   <trackNumber>11</trackNumber>
   <trackLength>398349.125</trackLength>
   <trackFileName>scene_eight__the_spirit_carries_on.mp3</trackFileName>
   <trackFileKey>6722e70adaf9291552db559f41506a07</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/6722e70adaf9291552db559f41506a07?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
  <item>
   <trackId>12034</trackId>
   <trackTitle>Scene Nine - Finally Free</trackTitle>
   <trackNumber>12</trackNumber>
   <trackLength>719864.25</trackLength>
   <trackFileName>scene_nine__finally_free.mp3</trackFileName>
   <trackFileKey>57b4ce3a89b5c02c8b119f11faf1ba03</trackFileKey>
   <downloadURL>
    http://content.mp3tunes.com/storage/lockerget/57b4ce3a89b5c02c8b119f11faf1ba03?sid=ec08029c87e05b2c49b6ac0cd194b68b
   </downloadURL>
   <albumTitle>Scenes From A Memory</albumTitle>
   <albumYear>1999</albumYear>
   <artistName>Dream Theater</artistName>
  </item>
 </trackList>
</mp3tunes>

Example 2.13. Listing the playlists in a user's locker (XML)


http://ws.mp3tunes.com/api/v0/lockerData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=xml&type=playlist

<mp3tunes>
 <item>
  <playlistId>1676</playlistId>
  <title>Work</title>
  <fileName>work_playlist.m3u</fileName>
  <fileCount>12</fileCount>
  <dateModified/>
 </item>
 <item>
  <playlistId>1337</playlistId>
  <title>Programming music</title>
  <fileName>music_f0r_t3h_c0d3.m3u</fileName>
  <fileCount>65535</fileCount>
  <dateModified/>
 </item>
 <item>
  <playlistId>1685</playlistId>
  <title>Dave Matthews Hour</title>
  <fileName>dave_matthews_hour.m3u</fileName>
  <fileCount>17</fileCount>
  <dateModified/>
 </item>
</mp3tunes>

Streaming

The streaming related methods retrieve audio files from locker storage.

lockerGet

http://content.mp3tunes.com/storage/lockerGet/<file key>?sid=<session id>&partner_token=<partner token>

parameters

sid (required)

A valid session id, received from the “login” method.

partner_token (required)

A Partner Token is used to uniquely identify and authenticate all entities using API's to communicate with MP3tunes.com. If you do not already have a partner token you may request one from the partner page.

fileformat (optional)

This parameter specifies a transcoding format to be used. Currently mp3 is the only option supported.

The lockerGet method is used to retrieve audio files from a user's locker. "Streaming" is achieved through a progressive download using this method. Audio files will be retrieved in the same format in which they were uploaded unless the fileformat parameter is used. This method returns specific Response Headers which indicate success or failure.

Chapter 3. Oboe Locker Syncing API

Table of Contents

Overview
Authentication
login
accountData

Overview

This section focuses on the portions of the API which are used for syncing MP3tunes lockers. The process used to sync music from an MP3tunes locker contains the following steps:

  • Authentication; Logging in and receiving a session id, retrieving account data.

  • Organization; Building a list of songs to sync, specifying sync options.

  • Syncing; Sending and retrieving songs and playlists from a users' Locker.

Authentication

Authentication allows the server to generate a session for the user. Without a session you will not be able to sync, or collect data about a user account.

login

https://shop.mp3tunes.com/api/v0/login?username=<username>&password=<password>&partner_token=<partner token>&output=<output format>

parameters

partner_token (required)

A Partner Token is used to uniquely identify and authenticate all entities using API's to communicate with MP3tunes.com. If you do not already have a partner token you may request one from the partner page.

username (required)

A valid MP3tunes account username. LINK TO SECTION COVERING ACCOUNT CREATION API CALLS HERE

password (required)

A valid MP3tunes account password. LINK TO SECTION COVERING ACCOUNT CREATION API CALLS HERE

output (optional)

Your preferred output format. These include xml, and json.

The login method attempts to authenticate the received user credentials and setup a session to be used with all subsequent requests. On success the 'status' parameter is set to 1, and a valid session id is returned. If authentication fails the 'status' parameter is set to 0, and the 'errorMessage' parameter is populated with appropriate error messages detailing what caused the call to fail.

Example 3.1. Successful authentication response (JSON)


https://shop.mp3tunes.com/api/v0/login?username=apitest@example.com&password=apitestpassword&partner_token=XXXXXXXXXX&output=json

{"status":1,
 "session_id":"ec08029c87e05b2c49b6ac0cd194b68b",
 "username":"apitest@example.com",
 "errorMessage":null}

Example 3.2. Successful authentication response (XML)


https://shop.mp3tunes.com/api/v0/login?username=apitest@example.com&password=apitestpassword&partner_token=XXXXXXXXXX&output=xml

<mp3tunes>
 <status>1</status>
 <session_id>ec08029c87e05b2c49b6ac0cd194b68b</session_id>
 <username>apitest@example.com</username>
 <errorMessage/>
</mp3tunes>

Example 3.3. Unsuccessful authentication response (JSON)


https://shop.mp3tunes.com/api/v0/login?username=apitest@example.com&password=apitestpassword&partner_token=invalidtoken&output=json

{"status":0,
 "errorMessage":"The partner_token input parameter failed validation."}

Example 3.4. Unsuccessful authentication response (XML)


https://shop.mp3tunes.com/api/v0/login?username=apitest@example.com&password=apitestpassword&partner_token=invalidtoken&output=xml

<mp3tunes>
 <status>0</status>
 <errorMessage>
  The partner_token input parameter failed validation.
 </errorMessage>
</mp3tunes>

accountData

http://ws.mp3tunes.com/api/v0/accountData?sid=<session id>&partner_token=<partner token>&output=<output format>

parameters

sid (required)

A valid session id, received from the “login” method.

partner_token (required)

A valid partner token. A Partner Token is used to uniquely identify and authenticate all entities using API's to communicate with MP3tunes.com. If you do not already have a partner token you may request one from the partner page.

output (optional)

Your preferred output format. These include xml, and json.

The accountData method retrieves information about a user account. This method will tell you what subscription level a user account has as well as the users' email address, name, and nickname.

Example 3.5. Successful accountData response (JSON)


http://ws.mp3tunes.com/api/v0/accountData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=json

{"user": {"email":"apitest@example.com",
          "nickName":null,
          "firstName":"Robert",
          "lastName":"Paulson",
          "subscriptions": [{"name":"user_locker_annual",
                             "description":"Locker Account - Annual"}]}}

Example 3.6. Successful accountData response (XML)


http://ws.mp3tunes.com/api/v0/accountData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=xml

<mp3tunes>
 <user>
  <email>apitest@example.com</email>
  <nickName/>
  <firstName>Robert</firstName>
  <lastName>Paulson</lastName>
  <subscriptions>
   <item>
    <name>user_locker_annual</name>
    <description>Locker Account - Annual</description>
   </item>
  </subscriptions>
 </user>
</mp3tunes>

Example 3.7. Unsuccessful accountData response (JSON)


http://ws.mp3tunes.com/api/v0/accountData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=json

{"status":0,
 "errorMessage":"Not logged in"}

Example 3.8. Unsuccessful accountData response (XML)


http://ws.mp3tunes.com/api/v0/accountData?sid=ec08029c87e05b2c49b6ac0cd194b68b&output=xml

<mp3tunes>
 <status>0</status>
 <errorMessage>Not logged in</errorMessage>
</mp3tunes>

Appendix A. Response Headers

All methods which deal with storage - lockerGet, lockerPut, etc - return HTTP headers to denote success or failure. The two important headers are "X-MP3tunes-ErrorNo" and "X-MP3tunes-ErrorString".

Response Headers

200

X-MP3tunes-ErrorNo: 200001

X-MP3tunes-ErrorString: Request Successful

400

X-MP3tunes-ErrorNo: 400002

X-MP3tunes-ErrorString: File identification error

Files in Oboe storage are identified by unique file keys, generated from the hash of the content of files. When a file is sent to MP3tunes for storage, the file key (the hash of the content of the file) is sent along with it. This error occurs when the MD5 hash used for a file key is calculated on the server and does not match what was sent up with the file.

401

X-MP3tunes-ErrorNo: 401001

X-MP3tunes-ErrorString: Authentication Error

This error occurs when there is an attempt to use a session which has expired on the server. If this occurs, call the login method to retrieve a new session id.

403

X-MP3tunes-ErrorNo: 403001

X-MP3tunes-ErrorString: Empty File Error

This error occurs when a file sent to MP3tunes for storage is zero bytes in length.

404

X-MP3tunes-ErrorNo: 404001

X-MP3tunes-ErrorString: File Not Found Error

This error occurs when a file is requested from storage which no longer exists.

409

X-MP3tunes-ErrorNo: 409001

X-MP3tunes-ErrorString: CRC Error

In order to identify actual file key mismatch errors a CRC is used to identify data loss or corruption when a file is transfered over a network for storage. This way if a file is corrupted while uploading another attempt can be made.

413

X-MP3tunes-ErrorNo: 413001

X-MP3tunes-ErrorString: File Too Large Error

Although there is no overall size limitation for an MP3tunes Oboe locker, there is a limit of 20 Megabytes per file.

415

X-MP3tunes-ErrorNo: 415001

X-MP3tunes-ErrorString: File Format Not Supported Error

Some file formats, such as FLAC and ALAC, are not supported at this time.

500

X-MP3tunes-ErrorNo: 500001

X-MP3tunes-ErrorString: Storage Subsystem Error

This error occurs when there is a problem with our storage system.