OvhApi

Official OVH Perl wrapper upon the OVH RESTful API. (c) OVH SAS
git clone https://git.onna.be/OvhApi.git
Log | Files | Refs | LICENSE

commit 8d2bdb6247f62c564d77a56d74327ce5e9c708f4
Author: Paco Esteban <paco@onna.be>
Date:   Mon, 12 Sep 2016 23:03:38 +0200

first commit

Diffstat:
.gitignore | 31+++++++++++++++++++++++++++++++
.travis.yml | 10++++++++++
Build.PL | 12++++++++++++
Changes | 6++++++
LICENSE | 26++++++++++++++++++++++++++
META.json | 57+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.md | 137+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
cpanfile | 6++++++
lib/OvhApi.pm | 358+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
lib/OvhApi/Answer.pm | 200+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
minil.toml | 4++++
t/00_compile.t | 9+++++++++
12 files changed, 856 insertions(+), 0 deletions(-)

diff --git a/.gitignore b/.gitignore @@ -0,0 +1,31 @@ +/.build/ +/_build/ +/Build +/Build.bat +/blib +/Makefile +/pm_to_blib + +/carton.lock +/.carton/ +/local/ + +nytprof.out +nytprof/ + +cover_db/ + +*.bak +*.old +*~ +*.swp +*.o +*.obj + +!LICENSE + +/_build_params + +MYMETA.* + +/OvhApi-* diff --git a/.travis.yml b/.travis.yml @@ -0,0 +1,10 @@ +language: perl +sudo: false +perl: + - "5.12" + - "5.14" + - "5.16" + - "5.18" + - "5.20" + - "5.22" + diff --git a/Build.PL b/Build.PL @@ -0,0 +1,12 @@ +# ========================================================================= +# THIS FILE IS AUTOMATICALLY GENERATED BY MINILLA. +# DO NOT EDIT DIRECTLY. +# ========================================================================= + +use 5.008_001; +use strict; + +use Module::Build::Tiny 0.035; + +Build_PL(); + diff --git a/Changes b/Changes @@ -0,0 +1,6 @@ +Revision history for Perl extension OvhApi + +{{$NEXT}} + + - original version + diff --git a/LICENSE b/LICENSE @@ -0,0 +1,26 @@ +Copyright (c) 2013, OVH SAS. +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 OVH SAS 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 OVH SAS 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 OVH SAS AND 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. + diff --git a/META.json b/META.json @@ -0,0 +1,57 @@ +{ + "abstract" : "Official OVH Perl wrapper upon the OVH RESTful API.", + "author" : [ + ", OVH SAS." + ], + "dynamic_config" : 0, + "generated_by" : "Minilla/v3.0.4, CPAN::Meta::Converter version 2.150005", + "license" : [ + "unknown" + ], + "meta-spec" : { + "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", + "version" : "2" + }, + "name" : "OvhApi", + "no_index" : { + "directory" : [ + "t", + "xt", + "inc", + "share", + "eg", + "examples", + "author", + "builder" + ] + }, + "prereqs" : { + "configure" : { + "requires" : { + "Module::Build::Tiny" : "0.035" + } + }, + "develop" : { + "requires" : { + "Test::CPAN::Meta" : "0", + "Test::MinimumVersion::Fast" : "0.04", + "Test::PAUSE::Permissions" : "0.04", + "Test::Pod" : "1.41", + "Test::Spellunker" : "v0.2.7" + } + }, + "runtime" : { + "requires" : { + "perl" : "5.008001" + } + }, + "test" : { + "requires" : { + "Test::More" : "0.98" + } + } + }, + "release_status" : "unstable", + "version" : "1", + "x_serialization_backend" : "JSON::PP version 2.27300" +} diff --git a/README.md b/README.md @@ -0,0 +1,137 @@ +# NAME + +OvhApi - Official OVH Perl wrapper upon the OVH RESTful API. + +# SYNOPSIS + + use OvhApi; + + my $Api = OvhApi->new(type => OvhApi::OVH_API_EU, applicationKey => $AK, applicationSecret => $AS, consumerKey => $CK); + my $Answer = $Api->get(path => '/me'); + +# DESCRIPTION + +This module is an official Perl wrapper that OVH provides in order to offer a simple way to use its RESTful API. +`OvhApi` handles the authentication layer, and uses `LWP::UserAgent` in order to run requests. + +Answer are retured as instances of [OvhApi::Answer](https://metacpan.org/pod/OvhApi::Answer). + +# CLASS METHODS + +## Constructor + +There is only one constructor: `new`. + +Its parameters are: + + Parameter Mandatory Default Usage + ------------ ------------ ---------- -------- + type Carp if missing OVH_API_EU() Determine if you'll use european or canadian OVH API (possible values are OVH_API_EU and OVH_API_CA) + timeout No 10 Set the timeout LWP::UserAgent will use + applicationKey Yes - Your application key + applicationSecret Yes - Your application secret + consumerKey Yes, unless for a credential request - Your consumer key + +## OVH\_API\_EU + +[Constant](https://metacpan.org/pod/constant) that points to the root URL of OVH european API. + +## OVH\_API\_CA + +[Constant](https://metacpan.org/pod/constant) that points to the root URL of OVH canadian API. + +## setRequestTimeout + +This method changes the timeout `LWP::UserAgent` uses. You can set that in [new](#constructor) instead. + +Its parameters are: + + Parameter Mandatory + ------------ ------------ + timeout Yes + +# INSTANCE METHODS + +## rawCall + +This is the main method of that wrapper. This method will take care of the signature, of the JSON conversion of your data, and of the effective run of the query. + +Its parameters are: + + Parameter Mandatory Default Usage + ------------ ------------ ---------- -------- + path Yes - The API URL you want to request + method Yes - The HTTP method of the request (GET, POST, PUT, DELETE) + body No '' The body to send in the query. Will be ignore on a GET + noSignature No false If set to a true value, no signature will be send + +## get + +Helper method that wraps a call to: + + rawCall(method => 'get"); + +All parameters are forwarded to [rawCall](#rawcall). + +## post + +Helper method that wraps a call to: + + rawCall(method => 'post'); + +All parameters are forwarded to [rawCall](#rawcall). + +## put + +Helper method that wraps a call to: + + rawCall(method => 'put'); + +All parameters are forwarded to [rawCall](#rawcall). + +## delete + +Helper method that wraps a call to: + + rawCall(method => 'delete'); + +All parameters are forwarded to [rawCall](#rawcall). + +## requestCredentials + +This method will request a Consumer Key to the API. That credential will need to be validated with the link returned in the answer. + +Its parameters are: + + Parameter Mandatory + ------------ ------------ + accessRules Yes + +The `accessRules` parameter is an ARRAY of HASHes. Each hash contains these keys: + +- method: an HTTP method among GET, POST, PUT and DELETE. ALL is a special values that includes all the methods; +- path: a string that represents the URLs the credential will have access to. `*` can be used as a wildcard. `/*` will allow all URLs, for example. + +### Example + + my $Api = OvhApi->new(type => OvhApi::OVH_API_EU, applicationKey => $AK, applicationSecret => $AS, consumerKey => $CK); + my $Answer = $Api->requestCredentials(accessRules => [ { method => 'ALL', path => '/*' }]); + + if ($Answer) + { + my ($consumerKey, $validationUrl) = @{ $Answer->content}{qw{ consumerKey validationUrl }}; + + # $consumerKey contains the newly created Consumer Key + # $validationUrl contains a link to OVH website in order to login an OVH account and link it to the credential + } + +# SEE ALSO + +The guts of module are using: `LWP::UserAgent`, `JSON`, `Digest::SHA1`. + +# COPYRIGHT + +Copyright (c) 2013, OVH SAS. +All rights reserved. + +This library is distributed under the terms of `license.txt`. diff --git a/cpanfile b/cpanfile @@ -0,0 +1,6 @@ +requires 'perl', '5.008001'; + +on 'test' => sub { + requires 'Test::More', '0.98'; +}; + diff --git a/lib/OvhApi.pm b/lib/OvhApi.pm @@ -0,0 +1,358 @@ +package OvhApi; + +use strict; +use warnings; + +our $VERSION = 1.0; + + +use OvhApi::Answer; + +use Carp qw{ carp croak }; +use List::Util 'first'; +use LWP::UserAgent (); +use JSON (); +use Digest::SHA1 'sha1_hex'; + + + +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +# Class constants + +use constant { + OVH_API_EU => 'https://eu.api.ovh.com/1.0', + OVH_API_CA => 'https://ca.api.ovh.com/1.0', +}; + +# End - Class constants +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # + + + +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +# Class variables + +my $UserAgent = LWP::UserAgent->new(timeout => 10); +my $Json = JSON->new->allow_nonref; + +my @accessRuleMethods = qw{ GET POST PUT DELETE }; + +# End - Class variables +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # + + + +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +# Class methods + +sub new +{ + my @keys = qw{ applicationKey applicationSecret consumerKey }; + + my ($class, %params) = @_; + + if (my @missingParameters = grep { not $params{$_} } qw{ applicationKey applicationSecret }) + { + local $" = ', '; + croak "Missing parameter: @missingParameters"; + } + + unless ($params{'type'} and grep { $params{'type'} eq $_ } (OVH_API_EU, OVH_API_CA)) + { + carp 'Missing or invalid type parameter: defaulting to OVH_API_EU'; + } + + my $self = { + _type => ($params{'type'} or OVH_API_EU), + }; + + @$self{@keys} = @params{@keys}; + + bless $self, $class; +} + +sub setRequestTimeout +{ + my ($class, %params) = @_; + + if ($params{'timeout'} =~ /^\d+$/) + { + $UserAgent->timeout($params{'timeout'}); + } + elsif (exists $params{'timeout'}) + { + carp "Invalid timeout: $params{'timeout'}"; + } + else + { + carp 'Missing parameter: timeout'; + } +} + +# End - Class methods +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # + + + +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +# Instance methods + +sub rawCall +{ + my ($self, %params) = @_; + + my $method = lc $params{'method'}; + my $url = $self->{'_type'} . (substr($params{'path'}, 0, 1) eq '/' ? '' : '/') . $params{'path'}; + + my %httpHeaders; + + my $body = ''; + my %content; + + if ($method ne 'get' and $method ne 'delete') + { + $body = $Json->encode($params{'body'}); + + $httpHeaders{'Content-type'} = 'application/json'; + $content{'Content'} = $body; + } + + unless ($params{'noSignature'}) + { + my $now = $self->_timeDelta + time; + + $httpHeaders{'X-Ovh-Consumer'} = $self->{'consumerKey'}, + $httpHeaders{'X-Ovh-Timestamp'} = $now, + $httpHeaders{'X-Ovh-Signature'} = '$1$' . sha1_hex(join('+', ( + # Full signature is '$1$' followed by the hex digest of the SHA1 of all these data joined by a + sign + $self->{'applicationSecret'}, # Application secret + $self->{'consumerKey'}, # Consumer key + uc $method, # HTTP method (uppercased) + $url, # Full URL + $body, # Full body + $now, # Curent OVH server time + ))); + } + + $httpHeaders{'X-Ovh-Application'} = $self->{'applicationKey'}, + + return OvhApi::Answer->new(response => $UserAgent->$method($url, %httpHeaders, %content)); +} + +sub requestCredentials +{ + my ($self, %params) = @_; + + croak 'Missing parameter: accessRules' unless $params{'accessRules'}; + croak 'Invalid parameter: accessRules' if ref $params{'accessRules'} ne 'ARRAY'; + + my @rules = map { + croak 'Invalid access rule: must be HASH ref' if ref ne 'HASH'; + + my %rule = %$_; + + $rule{'method'} = uc $rule{'method'}; + + croak 'Access rule must have method and path keys' unless $rule{'method'} and $rule{'path'}; + croak 'Invalid access rule method' unless first { $_ eq $rule{'method'} } (@accessRuleMethods, 'ALL'); + + if ($rule{'method'} eq 'ALL') + { + map { path => $rule{'path'}, method => $_ }, @accessRuleMethods; + } + else + { + \%rule + } + } @{ $params{'accessRules'} }; + + return $self->post(path => '/auth/credential/', noSignature => 1, body => { accessRules => \@rules }); +} + +# Generation of helper subs: simple wrappers to rawCall +# Generate: get(), post(), put(), delete() +{ + no strict 'refs'; + + for my $method (qw{ get post put delete }) + { + *$method = sub { rawCall(@_, 'method', $method ) }; + } +} + +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# Private part + +sub _timeDelta +{ + my ($self, %params) = @_; + + unless (defined $self->{'_timeDelta'}) + { + if (my $ServerTimeResponse = $self->get(path => 'auth/time', noSignature => 1)) + { + $self->{'_timeDelta'} = ($ServerTimeResponse->content - time); + } + else + { + return 0; + } + } + + return $self->{'_timeDelta'}; +} + +# End - Instance methods +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # + + +return 42; + + +__END__ + +=head1 NAME + +OvhApi - Official OVH Perl wrapper upon the OVH RESTful API. + +=head1 SYNOPSIS + + use OvhApi; + + my $Api = OvhApi->new(type => OvhApi::OVH_API_EU, applicationKey => $AK, applicationSecret => $AS, consumerKey => $CK); + my $Answer = $Api->get(path => '/me'); + +=head1 DESCRIPTION + +This module is an official Perl wrapper that OVH provides in order to offer a simple way to use its RESTful API. +C<OvhApi> handles the authentication layer, and uses C<LWP::UserAgent> in order to run requests. + +Answer are retured as instances of L<OvhApi::Answer|OvhApi::Answer>. + +=head1 CLASS METHODS + +=head2 Constructor + +There is only one constructor: C<new>. + +Its parameters are: + + Parameter Mandatory Default Usage + ------------ ------------ ---------- -------- + type Carp if missing OVH_API_EU() Determine if you'll use european or canadian OVH API (possible values are OVH_API_EU and OVH_API_CA) + timeout No 10 Set the timeout LWP::UserAgent will use + applicationKey Yes - Your application key + applicationSecret Yes - Your application secret + consumerKey Yes, unless for a credential request - Your consumer key + +=head2 OVH_API_EU + +L<Constant|constant> that points to the root URL of OVH european API. + +=head2 OVH_API_CA + +L<Constant|constant> that points to the root URL of OVH canadian API. + +=head2 setRequestTimeout + +This method changes the timeout C<LWP::UserAgent> uses. You can set that in L<new|/Constructor> instead. + +Its parameters are: + + Parameter Mandatory + ------------ ------------ + timeout Yes + +=head1 INSTANCE METHODS + +=head2 rawCall + +This is the main method of that wrapper. This method will take care of the signature, of the JSON conversion of your data, and of the effective run of the query. + +Its parameters are: + + Parameter Mandatory Default Usage + ------------ ------------ ---------- -------- + path Yes - The API URL you want to request + method Yes - The HTTP method of the request (GET, POST, PUT, DELETE) + body No '' The body to send in the query. Will be ignore on a GET + noSignature No false If set to a true value, no signature will be send + +=head2 get + +Helper method that wraps a call to: + + rawCall(method => 'get"); + +All parameters are forwarded to L<rawCall|/rawCall>. + +=head2 post + +Helper method that wraps a call to: + + rawCall(method => 'post'); + +All parameters are forwarded to L<rawCall|/rawCall>. + +=head2 put + +Helper method that wraps a call to: + + rawCall(method => 'put'); + +All parameters are forwarded to L<rawCall|/rawCall>. + +=head2 delete + +Helper method that wraps a call to: + + rawCall(method => 'delete'); + +All parameters are forwarded to L<rawCall|/rawCall>. + +=head2 requestCredentials + +This method will request a Consumer Key to the API. That credential will need to be validated with the link returned in the answer. + +Its parameters are: + + Parameter Mandatory + ------------ ------------ + accessRules Yes + +The C<accessRules> parameter is an ARRAY of HASHes. Each hash contains these keys: + +=over + +=item * method: an HTTP method among GET, POST, PUT and DELETE. ALL is a special values that includes all the methods; + +=item * path: a string that represents the URLs the credential will have access to. C<*> can be used as a wildcard. C</*> will allow all URLs, for example. + +=back + +=head3 Example + + my $Api = OvhApi->new(type => OvhApi::OVH_API_EU, applicationKey => $AK, applicationSecret => $AS, consumerKey => $CK); + my $Answer = $Api->requestCredentials(accessRules => [ { method => 'ALL', path => '/*' }]); + + if ($Answer) + { + my ($consumerKey, $validationUrl) = @{ $Answer->content}{qw{ consumerKey validationUrl }}; + + # $consumerKey contains the newly created Consumer Key + # $validationUrl contains a link to OVH website in order to login an OVH account and link it to the credential + } + +=head1 SEE ALSO + +The guts of module are using: C<LWP::UserAgent>, C<JSON>, C<Digest::SHA1>. + +=head1 COPYRIGHT + +Copyright (c) 2013, OVH SAS. +All rights reserved. + +This library is distributed under the terms of C<license.txt>. + +=cut + diff --git a/lib/OvhApi/Answer.pm b/lib/OvhApi/Answer.pm @@ -0,0 +1,200 @@ +package OvhApi::Answer; + +use strict; +use warnings; + +our $VERSION = 1.0; + + +use overload ( + bool => \&isSuccess, + '!' => \&isFailure, + fallback => 0, +); + +use Scalar::Util 'blessed'; +use Carp qw{ carp croak }; +use JSON (); + + + +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +# Class variables + +my $Json = JSON->new->allow_nonref; + +# End - Class variables +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # + + + +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +# Class methods + +sub new +{ + my ($class, %params) = @_; + + unless ($params{'response'}) + { + croak 'Missing parameter: response'; + } + + unless (blessed $params{'response'} and $params{'response'}->isa('HTTP::Response')) + { + croak 'Invalid parameter: reponse'; + } + + bless { response => $params{'response'} }, $class; +} + +# End - Class methods +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # + + + +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +# Instance methods + +sub isSuccess +{ + my ($self) = @_; + + return $self->{'response'}->is_success; +} + +sub isFailure +{ + my ($self) = @_; + + return not $self->isSuccess; +} + + +sub content +{ + my ($self) = @_; + + if ($self->isFailure) + { + carp 'Fetching content from a failed OvhApi::Response Object'; + return; + } + + return $self->_generateContent; +} + +sub error +{ + my ($self) = @_; + + return $self ? '' : $self->_generateContent->{'message'}; +} + +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# private part + +sub _generateContent +{ + my ($self) = @_; + + my $content; + + if ($self->{'response'}->header('Client-Warning') and $self->{'response'}->header('Client-Warning') eq 'Internal response') + { + return { message => 'Internal LWP::UserAgent error : ' . $self->{'response'}->content }; + } + + eval { $content = $Json->decode($self->{'response'}->content); 1; } or do { + carp 'Failed to parse JSON content from the answer: ', $self->{'response'}->content; + return; + }; + + return $content; +} + +# End - Instance methods +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # + + +return 42; + +__END__ + +=head1 NAME + +OvhApi::Answer - Response to a request run with C<OvhApi>. + +=head1 SYNOPSIS + + my $Answer = $Api->get(path => '/me'); + + if ($Answer) + { + # Success: can fetch content and process + my $content = $Answer->content; + } + else + { + # Request failed: stop here and retrieve the error + my $error = $Answer->error; + } + +=head1 DESCRIPTION + +This module represents a response to a query run with C<OvhApi>. It is build upon a C<HTTP::Request> object. + +=head1 CLASS METHODS + +=head2 Constructor + +There is only one constructor: C<new>. + +Its parameters are: + + Parameter Mandatory Default Usage + ------------ ------------ ---------- -------- + response Yes - An HTTP::Response object return by LWP::UserAgent + +=head1 INSTANCE METHODS + +=head2 content + +Returns the content of the answer. This method will C<carp> if the answer is an error. + +It takes no parameter. + +=head2 error + +Returns the error message of the answer, or an empty string if the answer is a success. + +It takes no parameter. + +=head2 isSuccess + +Forwards a call to C<HTTP::Response::is_error> in the inner C<HTTP::Response> of the answer. Returns true is the request was a success, false otherwise. + +It takes no parameter. + +This method is used for the C<bool> L<overload|overload>. + +=head2 isFailure + +Helper method which returns the boolean negation of L<isSuccess|/isSuccess>. + +It takes no parameter. + +=head1 SEE ALSO + +The guts of module are using: C<JSON>. + +=head1 COPYRIGHT + +Copyright (c) 2013, OVH SAS. +All rights reserved. + +This library is distributed under the terms of C<license.txt>. + +=cut + + diff --git a/minil.toml b/minil.toml @@ -0,0 +1,4 @@ +name = "OvhApi" +# badges = ["travis"] +module_maker="ModuleBuildTiny" +license="bsd" diff --git a/t/00_compile.t b/t/00_compile.t @@ -0,0 +1,9 @@ +use strict; +use Test::More 0.98; + +use_ok $_ for qw( + OvhApi +); + +done_testing; +