WebService::Soundcloud - Thin wrapper around Soundcloud RESTful API!
Version 0.02
#!/usr/bin/perl use WebService::Soundcloud; my $scloud = WebService::Soundcloud->new($client_id, $client_secret, { redirect_uri => 'http://mydomain.com/callback' } ); # Now get authorization url my $authorization_url = $scloud->get_authorization_url(); # Redirect the user to authorization url use CGI; my $q = new CGI; $q->redirect($authorization_url); # In your '/callback' handler capture code params # Check for error if ($q->param(error)) { die "Authorization Failed: ". $q->param('error'); } # Get authorization code my $code = $q->param('code'); # Get Access Token my $access_token = $scloud->get_access_token($code); # Save access_token and refresh_token, expires_in, scope for future use my $oauth_token = $access_token->{access_token}; # OAuth Dance is completed :-) Have fun now. # Default request and response formats are 'json' # a GET request '/me' - gets users details my $user = $scloud->get('/me'); # a PUT request '/me' - updated users details my $user = $scloud->put('/me', encode_json( { 'user' => { 'description' => 'Have fun with Perl wrapper to Soundcloud API' } } ) ); # Comment on a Track POSt request usage my $comment = $scloud->post('/tracks/<track_id>/comments', { body => 'I love this hip-hop track' } ); # Delete a track my $track = $scloud->delete('/tracks/{id}'); # Download a track my $file_path = $scloud->download('<track_id>', $dest_file);
This module provides a wrapper around Soundcloud RESTful API to work with different kinds of soundcloud resources. It contains many functions for convenient use rather than standard Soundcloud RESTful API.
The complete API is documented at http://developers.soundcloud.com/docs.
In order to use this module you will need to register your application with Soundcloud at http://soundcloud.com/you/apps : your application will be given a client ID and a client secret which you will need to use to connect.
Returns a newly created WebService::Soundcloud object. The first argument is $client_id, the second argument is $client_secret - these are required and will have been provided when you registered your application with Soundcloud The third optional argument is a HASHREF that contains additional parameters that may be required:
WebService::Soundcloud
This is the URI of your application to which the user will be redirected after they have authorised the connection with Soundcloud. This should be the same as the one provided when you registered your application and will be required for most applications.
Accessor for the Client ID that was provided when you registered your application.
Accessor for the Client Secret that was provided when you registered your application.
Accessor for the redirect_uri this can be passed as an option to the constructor or supplied later (before any connect call.) This should match to that provided when you registered your application.
It is the URI of your application that the user will be redirected (with the authorization code as a parameter,) after they have clicked "Connect" on the soundcloud connect page. This will not be used if you are using the credential based authentication to obtain the OAuth token (e.g if you are an application with no UI that is operating for a single user.)
This returns a HASHREF that is suitable to be used as the basic parameters in most places, containing the application credentials (ID and Secret) and redirect_uri
Returns the LWP::UserAgent object that will be used to connect to the API host
This method is used to get authorization url, user should be redirected for authenticate from soundcloud. This will return URL to which user should be redirected.
This method is used to receive access_token, refresh_token, scope, expires_in details from soundcloud once user is authenticated. access_token, refresh_token should be stored as it should be sent along with every request to access private resources on the user behalf.
The argument $code is required unless you are using credential based authentication, and will have been supplied to your redirect_uri after the user pressed "Connect" on the soundcloud connect page.
$code
redirect_uri
This method is used to get new access_token by exchanging refresh_token before the earlier access_token is expired. You will receive new access_token, refresh_token, scope and expires_in details from soundcloud. access_token, refresh_token should be stored as it should be sent along with every request to access private resources on the user behalf.
If a scope of 'non-expiring' was supplied at the time the initial tokem was obtained then this should not be necessary.
scope
This performs an HTTP request with the $method supplied to the supplied $url. The third argument $headers can be supplied to insert any required headers into the request, if $content is supplied it will be processed appropriately and inserted into the request.
An HTTP::Response will be returned and this should be checked to determine the status of the request.
This returns a decoded object corresponding to the URI given
It will for the response_format to 'json' for the request as parsing the XML is tricky given no schema.
This returns a decoded LIST REF of the list method specified by URI
Currently this will force response_format to 'json' as parsin the XML is tricky without a schema.
This method is used to dispatch GET request on the give URL(first argument). second argument is an anonymous hash request parameters to be send along with GET request. The third optional argument(<HEADERS>) is used to send headers. This method will return HTTP::Response object
This method is used to dispatch POST request on the give URL(first argument). second argument is the content to be posted to URL. The third optional argument(<HEADERS>) is used to send headers. This method will return HTTP::Response object
This method is used to dispatch PUT request on the give URL(first argument). second argument is the content to be sent to URL. The third optional argument(<HEADERS>) is used to send headers. This method will return HTTP::Response object
This method is used to dispatch DELETE request on the give URL(first argument). second optional argument is an anonymous hash request parameters to be send along with DELETE request. The third optional argument(<HEADERS>) is used to send headers. This method will return HTTP::Response object
This method is used to download a particular track id given as first argument. second argument is name of the destination path where the downloaded track will be saved to. This method will return the file path of downloaded track.
This subroutime is intended to be used as a callback on 'response_redirect' It processes the response to make a new request for the redirect with the Authorization header removed so that EC3 doesn't get confused.
Helper subroutine to determine if the code indicates a redirect.
Accessor for the request format to be used. Acceptable values are 'json' and 'xml'. The default is 'json'.
Accessor for the response format to be used. The allowed values are 'json' and 'xml'. The default is 'json'. This will cause the appropriate setting of the Accept header in requests.
This will return the parsed object corresponding to the response content passed as asn argument. It will select the appropriate parser based on the value of 'response_format'.
It will return undef if there is a problem with the parsing.
Please do not use these internal methods directly. They are internal to WebService::Soundcloud module itself. These can be renamed/deleted/updated at any point of time in future.
This method is used to get access_token from soundcloud. This will be called from get_access_token and get_access_token_refresh methods.
This method is used to get access_token_url of soundcloud RESTful API. This will be called from _access_token method.
This method is used to prepare absolute URL for a given path and request parameters.
This method is used to set extra headers to the current HTTP Request.
This method is used to write some text to STDERR.
Mohan Prasad Gutta, <mohanprasadgutta at gmail.com>
<mohanprasadgutta at gmail.com>
Jonathan Stowe jns+gh@gellyfish.co.uk
jns+gh@gellyfish.co.uk
Parts of this are extremely difficult to test properly so there almost certainly will be bugs, please feel free to fix and send me a patch if you find one.
You can find documentation for this module with the perldoc command. perldoc WebService::Soundcloud You can also look for information at:
RT: CPAN's request tracker (report bugs here) http://rt.cpan.org/NoAuth/Bugs.html?Dist=WebService-Soundcloud
AnnoCPAN: Annotated CPAN documentation http://annocpan.org/dist/WebService-Soundcloud
CPAN Ratings http://cpanratings.perl.org/d/WebService-Soundcloud
Search CPAN http://search.cpan.org/dist/WebService-Soundcloud/
Copyright 2013 Mohan Prasad Gutta. This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License. See http://dev.perl.org/licenses/ for more information.
To install WebService::Soundcloud, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::Soundcloud
CPAN shell
perl -MCPAN -e shell install WebService::Soundcloud
For more information on module installation, please visit the detailed CPAN module installation guide.