NAME

WebService::Soundcloud - Provide access to the Soundcloud API

SYNOPSIS

You can use the Full OAuth flow:

    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();

    # Now your appplication should redirect the user to the authorization uri
    # When the User has authenticated and approved the connection they will
    # in turn be redirected back to your redirect URI with either the grant code
    # (as code) or an error (as error) as query parameters

    # Get Access Token with the code provided as query parameter to the redirect
    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>;

    # a GET request '/me' - gets users details
    my $user = $scloud.get('/me');

    # a PUT request '/me' - updated users details
    my $user = $scloud.put('/me', to-json( { user => { description => 'Have fun with the Raku 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}');

or you can use direct credential based authorisation that can skip the redirections:

    use WebService::Soundcloud;


    my $sc = WebService::Soundcloud.new(:$client-id,:$client-secret,:$username,:$password);

    # Because the credentials were provided  the access-token can be requested directly
    # without the need for a grant code
    my $token = $sc.get-access-token();
    my $me = $sc.get-object('/me');
    my $tracks = $sc.get-list('/me/tracks');

DESCRIPTION

This module provides a wrapper around Soundcloud REST API to work with different kinds of soundcloud resources. It contains many functions for convenient use rather than standard Soundcloud REST 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. The client ID used in the tests will not work correctly for your own application as the callback URI is set to 'localhost'.

METHODS

method new

method new(Str :$!client-id!, Str :$!client-secret!, Str :$!redirect-uri, Str :$!scope, Str :$!username, Str :$!password, HTTP::UserAgent :$!ua )

Returns a newly created WebService::Soundcloud object. The first named 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. If username and password are provided then credentials based authentication will be performed.

An optional HTTP::UserAgent can be passed if there is some requirement for special configuration that isn't allowed for.

method client-id

Accessor for the Client ID that was provided when you registered your application.

method client-secret

Accessor for the Client Secret that was provided when you registered your application.

method redirect-uri

Accessor for the redirect-uri this can be passed as an option to the constructor or supplied later (before any connect call.) This must match that provided when you registered your application.

This can be supplied as an option to the constructor.

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.)

method basic-params

This returns a Hash that is suitable to be used as the basic parameters in most places, containing the application credentials (ID and Secret) and redirect-uri

method ua

Returns the HTTP::UserAgent object that will be used to connect to the API host

method get-authorization-url

method get-authorization-url(*%args)

This method is used to get the authorization ("connect") uri which the user should be redirected to authenticate with soundcloud and indicate they permit the connection to your application. This will return the URL to which user should be redirected.

Any additional named style arguments will be appended as query parameters to the URI.

method get-access-token

method get-access-token(Str $code?, *%args) returns Hash

This method is used to receive access-token, refresh-token, scope and expires-in details from Soundcloud once the 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.

method get-access-token-refresh

method get-access-token-refresh(Str $refresh-token, *%args)

This method is used to get a 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.

method request

method request(Str $method, URI $url, HTTP::Header $headers, %content?) returns HTTP::Response

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.

method get-object

method get-object($url, %params?, %headers? )

This returns a decoded object corresponding to the URI. %params is a Hash of query parameters that will be added to the request URI, %headers provides a set of additional header fields that will be added to the request.

method get-list

method get-list($url, %params?, %headers?)

This returns an Array of the list method specified by URI. %params is a Hash of query parameters that will be added to the request URI, %headers provides a set of additional header fields that will be added to the request.

• method get

method get( Str $path, %params?, %extra_headers? )

This method is used to dispatch GET request on the give URL(first argument). second argument is a Hash of request parameters to be send along with GET request. The third optional argument is used to add headers. This method will return a HTTP::Response object.

method post

method post(Str $path, $content, %extra_headers? )

This method is used to make a POST request on the given path. The second argument is the content to be posted to URL. The third optional argument are additional headers to be added to the request. This method will return a HTTP::Response object.

method put

method put( Str $path, $content, %extra_headers? )

This method is used to dispatch PUT request to the given URL second argument is the content to be sent to URL. The third optional argument is a set of aditional headers that will be added to the request. This method returns a HTTP::Response object.

method delete

method delete(Str $path, %params?, %extra_headers? )

This method is used to dispatch DELETE request to the given URL the second argument is a Hash of request parameters to be sent along with the DELETE request. Any additional named style parameters will be added to the headers of the request to be sent. This method returns a HTTP::Response object

method download

** NOT YET IMPLEMENTED **

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.

method request-format

Accessor for the request format to be used. The default is 'json' which should be suitable for all applications. If the format is set to something which Soundcloud can't deal with there will be a "406" ("Not acceptable") response from the API.

method response-format

Accessor for the response format to be used. The default is 'json'. If the format is set to something which Soundcloud can't deal with there will be a "406" ("Not acceptable") response from the API.

method parse-content

method parse-content(Str $content)

This will return the parsed object corresponding to the response content passed as an argument. Currently only JSON data is parsed.

It will return undef if there is a problem with the parsing.

method log

method log(Str() $msg)

This method is used to write some text to $*ERR if debug is a true value.