WebService::Edgecast - Perl interface to Edgecast's SOAP API
version 0.01.00
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);
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.
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.
SOAP::WSDL
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.
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:
WebService::Edgecast
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.
strCredential
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:
api_type
api_type : reporting endpoint : http://api.edgecast.com/v1/Reporting.asmx
reporting
api_type : realtime endpoint : http://api.edgecast.com/v1/RealTime.asmx
realtime
api_type : mediamanager endpoint : http://api.edgecast.com/v1/MediaManager.asmx
mediamanager
api_type : administration endpoint : http://api.edgecast.com/v1/Administration.asmx
administration
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.
endpoint
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:
BandwidthGet
my $client = WebService::Edgecast->new({ email => 'foo@yoo.com', password => '...', api_type => 'realtime', });
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.
set_api_type
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
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:
error
undef
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
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
EC:WebServices
See the SOAP::Lite example in the Edgecast API documentation for an example of where this value is being used internally.
SOAP::Lite
client_type
Defualt: p
p
This can either be p, for Partner, or c, for Customer. They represent two different APIs.
c
security_type
Default: bas
bas
The default, bas, stands for basic security. At the time of writing this is the only security type supported by Edgecast.
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.
CDN/Edgecast/Client/auto/
Moose is the object framwork this module is based on.
Moose
Home Page - http://www.iinteractive.com/moose
CPAN - http://search.cpan.org/search?query=Moose
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
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
Dist::Zilla::Plugin::WSDL
Please email the author directly for any support or bug related issues.
James Conerly <jconerly@cpan.org> 2010
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.
To install WebService::Edgecast, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::Edgecast
CPAN shell
perl -MCPAN -e shell install WebService::Edgecast
For more information on module installation, please visit the detailed CPAN module installation guide.