Although I’d normally write this article in Romanian I expect a wider audience for it, so I will post it in English.
Snippet
If you don’t want to read the entire article here are some shortcuts:
Dance-Tunes.com
Dance Tunes Logo
Dance-Tunes is a music online store, located in the Netherlands, where one can buy their favorite … dance tunes, of course. Organised in eight main genres (Downtempo, Dance, Techno/Minimal, Hardcore, Breaks, Electro/House, Hardstyle/Jump and Trance) Dance-Tunes has an extensive database of tunes, artists and labels.
The Public API
On the 22nd of February 2010, Dance-Tunes released their 1.0 version of the API. The main purpose of the API is to help create rich internet applications that are based on the information of tunes, artists, labels or charts. Developers are encouraged to use the public Dance-Tunes API to get creative and use the extensive library of labels, artists and tracks in their sites or applications.
Dance-Tunes has created a special page for developers where one can find all information about the public API. Each individual API call is explained and examples are given to show the correct structure of the calls and response. One can request an API key by logging in using the Dance-Tunes account details. The API key will be sent to the developer’s email address. One can download the API documentation in pdf format for printing and off-line viewing.
The PHP Client
The Dance-Tunes PHP API Client that I am releasing today, was written with intention of integrating into a Zend Framework application. As of this it follows the PHP File Formatting, Naming Conventions and Coding Style recommended by the Zend Framework Team.
It uses the Zend_Http and Zend_Exception packages from the Zend Framework classes. It can be used either with an entire Zend Framework application or as is. The dependencies can be load by themselves (just the 2 packages), or the Dancetunes class can be modified in order to be used in a simple PHP project. One can replace the use of Zend_Http package with the use of the cURL library and the Zend_Exception with the PHP base Exception.
Usage
Each of the documented function in the Dance-Tunes API has a corespondent wrapper method in the Dancetunes class that accepts the exact amount of parameters that the API requires, except the command and the session(params cmd and session) which are built in. For each session key, as the documentation specifies, a timestamp is updated on each request, and the session key is deleted if no request is performed for 6 hours. So, as a best practice, it is recommended to cache the session key locally for immediate access to the resources on other requests.
$dancetunes = new Dancetunes(DT_API_KEY);
if (!($sessionKey = $cache->load('sessionkey')))
{
$dancetunes->setUserName(DT_USERNAME);
$dancetunes->setPassword(DT_PASSWORD);
$sessionKey = $dancetunes->authenticate();
$cache->save($sessionKey, 'sessionkey');
}
$dancetunes->setSessionKey($sessionKey);
/* Get the first 10 releases */
$releases = $dancetunes->getNewReleases(11, 10, 1, 10);
/* Get a preview */
$audio = $dancetunes->getPreview( 123456 );
/* saving the audio content to disc */
file_put_contents('123456-tune-preview.mp3', $audio);
Responses
Dance-Tunes API will respond either with an XML string or with binary data (for artwork and preview). For the case of XML response I have created a Dancetunes_Vo class that takes a XML string and converts it into an array. Also for each response type I have created an individual class that extends the Dancetunes_Vo class and implements some particular methods for a specific result. For example the Dancetunes_NewReleases class will be the result of the Dancetunes::getNewReleases method and has a method for returning just the tunes info from the response, and another one to return the number of total possible tunes that can be returned on a specific request.
class Dancetunes_NewReleases extends Dancetunes_Vo {
public function getTracks() {
return $this->_array ['new_releases'] ['tune'];
}
public function getCount() {
return $this->_array ['new_releases'] ['total_count'];
}
}
These classes can be modified or extended in order to deal in a specific way with the XML response.
License
The package is released as an open source project under The New BSD License.
Copyright (c) 2010, George Enciu, ColorSoft System SRL, Romania
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the ColorSoft System SRL nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Change Log
2010-04-06
- Version 0.1 BETA released
2010-05-15
- Added a version written in simple PHP
- Still in 0.1 Beta
Download
All the code and download files can be found at the Google Code Project
ump($ex);
