/ 
WebService-Edgecast-0.01.00
River stage zero No dependents
/ WebService::Edgecast

NAME

WebService::Edgecast - Perl interface to Edgecast's SOAP API

VERSION

version 0.01.00

SYNOPSIS

use Data::Dumper;
use WebService::Edgecast;

my $client = WebService::Edgecast->new({
    email    => 'foo@yoo.com',
    password => '...',
    api_type => 'administration',
});

my $result = $client->CustomerGet({
    strCustomerId => '29D8'
});

print $client->error || Dumper($result);

THIS IS ALPHA SOFTWARE

I repeat, this is ALPHA software. For the time being use at your own risk, but if you do use it please report any found bugs or issues to the author. Once this module has done the rounds in a production environment and has been tweaked appropriately this disclaimer will be removed.

DESCRIPTION

This module implements a simiplified OO SOAP client for Edgecast's CDN API. It uses SOAP::WSDL to generate all the interface and type classes from Edgecast's public WSDL descriptions, thus it supports all the functions defined in Edgecast's API documentation.

    If you are developing against the Edgecast API I am assuming you have their API documentation in hand. Since this module simply provides an object interface to their API you'll be spending most of your time referencing their documentation for the details on supported functions.

For Example

In Edgecast's API documentation you might find the following method definition in the Real-Time Reporting section:

Method: BandwidthGet

Description: This method call will get the real time bandwidth (bps = bits
             per second) for a media type. Data updates every minute. 

Parameters:
    strCredential - The EdgeCast credential required to authenticate the client.
    strCustomerId - The unique alphanumeric account number (AN) of the customer,
                    such as "0002" or "00F3".
    intMediaType  - 2=Flash, 3=HTTP Large Object, 4=HTTP Small Object
    
Return Value:
    A double representing real time bits per second (bps).

This means that when using WebService::Edgecast all you have to do is invoke the desired method call on the object, and pass in the appropriate parameters in a hashref, ala:

my $result = $client->BandwidthGet({
    strCustomerId => '29D8',
    intMediaType  => 3,
});

Note that you do not have to pass in the strCredential parameter when calling these methods. This is because when you instantiate your WebService::Edgecast object you pass in your Edgecast email/password combo, and your strCredential is generated and automatically used for every subsequent method call you make.

API TYPES

At the time of this writing, Edgecast supports four different API's. For the purpose of this module I am refering to each API as an api_type, which is the value you pass into the constructor. They are:

1 Reporting - Access reporting features such as bytes transferred and hits

api_type : reporting endpoint : http://api.edgecast.com/v1/Reporting.asmx

2 Real Time - Access real time reporting such as connections and bandwidth

api_type : realtime endpoint : http://api.edgecast.com/v1/RealTime.asmx

3 Media Manager - Perform file / media management functions such as load and purge

api_type : mediamanager endpoint : http://api.edgecast.com/v1/MediaManager.asmx

4 Administration - for partners / resellers to manage their customers

api_type : administration endpoint : http://api.edgecast.com/v1/Administration.asmx

    NOTE: You do not need to worry about the endpoint values above when using this module. They are only there for reference so you know what the source of all the auto-generated code is.

So if you need to run a method from the RealTime Reporting API you need to make sure you instantiate your WebService::Edgecast object with the appropriate api_type. For the above example where we call the BandwidthGet method you would need to instantiate your object with the 'realtime' api_type:

my $client = WebService::Edgecast->new({
    email    => 'foo@yoo.com',
    password => '...',
    api_type => 'realtime',
});

Switching API Type at Runtime

If your application requires access to more than one api_type at run time you can either have several WebService::Edgecast objects, one for each type you need, OR you can use a single object and switch the api_type as needed. To do this use the set_api_type method. For example.

my $client = WebService::Edgecast->new({
    email    => 'foo@yoo.com',
    password => '...',
    api_type => 'administration',
});

my $result = $client->CustomerGet({...});

# Process result from Administration API

$client->set_api_type('realtime');

$result = $client->BandwidthGet({...}); 

# Process result from RealTime API

ERRORS

For any given method call WebService::Edgecast traps any errors returned and stuffs them into the object's error attribute, and returns undef as it's result. So to do error checking on the client side you'll probably want to use one of the following idioms:

my $result = $client->METHOD({...});

if ($client->error) {
    croak "Got error: " . $client->error;
} else {
    # Do something with data
}

  - OR - 

my $result = $client->METHOD({...})
    or croak "Got error: " . $client->error;

# Do something with data

OBJECT ATTRIBUTES

Beyond instantiating your object with required email, password, and api_type parameters, there are other attributes whose default values you can override to customize your SOAP client further. They all have resonable defaults that you probably wont need to modify, but in the case(s) where you do have to use different values WebService::Edgecast let's you do just that. They are:

  • uri

    Default: EC:WebServices

    See the SOAP::Lite example in the Edgecast API documentation for an example of where this value is being used internally.

  • client_type

    Defualt: p

    This can either be p, for Partner, or c, for Customer. They represent two different APIs.

  • security_type

    Default: bas

    The default, bas, stands for basic security. At the time of writing this is the only security type supported by Edgecast.

GENERATED CODE

As noted earlier, the bulk of this module is code automatically generated by SOAP::WSDL. If you start poking through the source tree you'll see that the namespace gets very deep and verbose... borderline horrific actually. I mean really:

WebService::Edgecast::auto::Reporting::Interface::EdgeCastWebServices::EdgeCastWebServicesSoap

Yuck!

The good news, however, is that the whole point of this module is to abstract that namespace from you so that all you have to deal with is the WebService::Edgecast namespace, and nothing more.

But if you're curious and want to poke around in the auto-generateed code you can find it under the CDN/Edgecast/Client/auto/ directory. A lot, if not most. of those modules have POD that's directly generated from the WSDL description. So if you don't have direct access to Edgecast's API documentation you can use the POD in those modules as an alternative reference.

SEE ALSO

Mooooooose

Moose is the object framwork this module is based on.

  • Home Page - http://www.iinteractive.com/moose

  • CPAN - http://search.cpan.org/search?query=Moose

Edgecast Documentation and WSDLs

The human-readable Edgecast API documentation for Partners and Customers can be obtained directly from Edgecast, and is avalialbe in PDF. WSDL descriptions for each of the 4 APIs can be found at the following URLs:

  • Reporting - http://api.edgecast.com/v1/Reporting.asmx?WSDL

  • RealTime - http://api.edgecast.com/v1/RealTime.asmx?WSDL

  • MediaManager - http://api.edgecast.com/v1/MediaManager.asmx?WSDL

  • Administration - http://api.edgecast.com/v1/Administration.asmx?WSDL

SOAP::WSDL and Dist::Zilla

This module was built using Dist::Zilla and one of its plugins that utilizes SOAP::WSDL.

  • Dist::Zilla Home Page - http://dzil.org

  • Dist::Zilla CPAN - http://search.cpan.org/search?query=Dist+Zilla

  • Dist::Zilla::Plugin::WSDL CPAN - http://search.cpan.org/search?query=Dist+Zilla+WSDL

SUPPORT

Please email the author directly for any support or bug related issues.

AUTHOR

James Conerly <jconerly@cpan.org> 2010

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by James Conerly.

This is free software, licensed under The Artistic License 2.0. Please see the LICENSE file included in this package for more detailed information.