Draft API Spec

This specification outlines all the features that will be implemented in this SDK. As the features are implemented in the SDK they will be made available via pure Ruby objects. You wont have to call the HTTP POST or process the XML directly to call these methods.

Person Methods

person_login

Will log in a person when passed a username (email) and password.

Arguments

• email
• password
• api_key

Example response

<?xml version="1.0" encoding="UTF-8"?>
  <person id="9999">
    <name>John Smith</name>
    <email>johnsmith@gmail.com</email>
  </person>
</xml>

or

<?xml version="1.0" encoding="UTF-8"?>
<person>
  <status>error</status>
  <error>
    <attribute>person</attribute>
    <message>invalid login</message>
  </error>
</person>

create_person

Will create a person record for this partner account.

Arguments

• api_key
• email
• name
• phone_number
• password
• county (for USA send "United States")
• us_zip_code (required if country is "United States")

Example response

<?xml version="1.0" encoding="UTF-8"?>
<person>
  <status>complete</status>
  <id>55908</id>
</person>

or

<?xml version="1.0" encoding="UTF-8"?>
<person>
  <status>error</status>
  <error>
    <attribute>country</attribute>
    <message>can't be blank</message>
  </error>
  <error>
    <attribute>phone_number</attribute>
    <message>can't be blank</message>
  </error>
</person>

get_person

Will return the information for a specific person.

Arguments

• api_key
• person_id

Example response

<?xml version="1.0" encoding="UTF-8"?>
  <person id="9999">
    <name>John Smith</name>
    <email>johnsmith@gmail.com</email>
  </person>
</xml>

list_people

Will return a list of all the people for this partner

Arguments

• api_key

Example response

<?xml version="1.0" encoding="UTF-8"?>
  <people>
    <person id="9998">


      <name>Joe Blow</name>
      <email>jblow@hotmail.com</email>
    </person>
    <person id="9999">
      <name>John Smith</name>
      <email>johnsmith@gmail.com</email>
    </person>
  </people>
</xml>

Album/Song Methods

create_album

Will create a new album

Arguments

• api_key
• person_id
• album_name
• artist_name (optional, can be left blank for "Various Artists")
• label_name (optional, will default to artist name if not supplied)
• upc (optional, will be auto-generated if not provided)
• stores (a comma seperated list of stores to send to)

Example response

<?xml version="1.0" encoding="UTF-8"?>
  <album id="50099">
    <person_id>9998</person_id>
    <album_name>Thriller</album_name>
    <artist_name>Michael Jackson</artist_name>
    <label_name>Sony</label_name>
    <upc>859700118818</upc>
      <stores>
        <store>iTunes</store>
        <store>Rhapsody</store>
        <store>AmazonMP3</store>
      </stores>
  </album>
</xml>

list_albums

show_album

takedown_album

add_song

Will add a song to an album, optionally specifying the Amazon S3 location of the audio file. If the audio file is not specified here it should be uploaded prior to finalizing the album.

Arguments

• api_key
• album_id
• song_name
• song_number (order it appears on the album)
• isrc (optional, will be auto-generated if blank)
• artist (if the album's artist is not supplied)
• free_download (applies to Amazon MP3 only)
• album_only (applies to Amazon MP3 only)
• s3_bucket (optional, location of audio file bucket)
• s3_filename (optional, filename of audio file in the S3 bucket)

Example response

<?xml version="1.0" encoding="UTF-8"?>
  <song id="440099">
    <album_id>50099</album_id>
    <person_id>9998</person_id>
    <song_name>Billy Jean</album_name>
    <label_name>Sony</label_name>
    <isrc>859700118818</isrc>
  </song>
</xml>

album_finalize

Will start the delivery process. No further changes can be made to the album at this point.

album_status

Will return the current status of the album. Can be: incomplete, queued, processing, delivered, live, error. If the current status is 'error' a message will be attached explaining the error.

Arguments

• api_key
• album_id

Example response

<?xml version="1.0" encoding="UTF-8"?>
  <album id="440099">
    <status>error</status>
    <message>Transcoding error</message>
  </album>
</xml>

or

<?xml version="1.0" encoding="UTF-8"?>
  <album id="440099">
    <status>live</status>
    <itunes_url>http://phobos.apple.com/itunes/album/91240979</itunes_url>
    <amazon_url>http://www.amazon.com/amazonmp3/album/982374986</amazon_url>
  </album>
</xml>