OvhApi

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

README.md (4849B)


      1 # NAME
      2 
      3 OvhApi - Official OVH Perl wrapper upon the OVH RESTful API.
      4 
      5 # SYNOPSIS
      6 
      7     use OvhApi;
      8 
      9     my $Api    = OvhApi->new(type => OvhApi::OVH_API_EU, applicationKey => $AK, applicationSecret => $AS, consumerKey => $CK);
     10     my $Answer = $Api->get(path => '/me');
     11 
     12 # DESCRIPTION
     13 
     14 This module is an official Perl wrapper that OVH provides in order to offer a simple way to use its RESTful API.
     15 `OvhApi` handles the authentication layer, and uses `LWP::UserAgent` in order to run requests.
     16 
     17 Answer are retured as instances of [OvhApi::Answer](https://metacpan.org/pod/OvhApi::Answer).
     18 
     19 # CLASS METHODS
     20 
     21 ## Constructor
     22 
     23 There is only one constructor: `new`.
     24 
     25 Its parameters are:
     26 
     27     Parameter           Mandatory                               Default                 Usage
     28     ------------        ------------                            ----------              --------
     29     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)
     30     timeout             No                                      10                      Set the timeout LWP::UserAgent will use
     31     applicationKey      Yes                                     -                       Your application key
     32     applicationSecret   Yes                                     -                       Your application secret
     33     consumerKey         Yes, unless for a credential request    -                       Your consumer key
     34 
     35 ## OVH\_API\_EU
     36 
     37 [Constant](https://metacpan.org/pod/constant) that points to the root URL of OVH european API.
     38 
     39 ## OVH\_API\_CA
     40 
     41 [Constant](https://metacpan.org/pod/constant) that points to the root URL of OVH canadian API.
     42 
     43 ## setRequestTimeout
     44 
     45 This method changes the timeout `LWP::UserAgent` uses. You can set that in [new](#constructor) instead.
     46 
     47 Its parameters are:
     48 
     49     Parameter           Mandatory
     50     ------------        ------------
     51     timeout             Yes
     52 
     53 # INSTANCE METHODS
     54 
     55 ## rawCall
     56 
     57 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.
     58 
     59 Its parameters are:
     60 
     61     Parameter           Mandatory                               Default                 Usage
     62     ------------        ------------                            ----------              --------
     63     path                Yes                                     -                       The API URL you want to request
     64     method              Yes                                     -                       The HTTP method of the request (GET, POST, PUT, DELETE)
     65     body                No                                      ''                      The body to send in the query. Will be ignore on a GET
     66     noSignature         No                                      false                   If set to a true value, no signature will be send
     67 
     68 ## get
     69 
     70 Helper method that wraps a call to:
     71 
     72     rawCall(method => 'get");
     73 
     74 All parameters are forwarded to [rawCall](#rawcall).
     75 
     76 ## post
     77 
     78 Helper method that wraps a call to:
     79 
     80     rawCall(method => 'post');
     81 
     82 All parameters are forwarded to [rawCall](#rawcall).
     83 
     84 ## put
     85 
     86 Helper method that wraps a call to:
     87 
     88     rawCall(method => 'put');
     89 
     90 All parameters are forwarded to [rawCall](#rawcall).
     91 
     92 ## delete
     93 
     94 Helper method that wraps a call to:
     95 
     96     rawCall(method => 'delete');
     97 
     98 All parameters are forwarded to [rawCall](#rawcall).
     99 
    100 ## requestCredentials
    101 
    102 This method will request a Consumer Key to the API. That credential will need to be validated with the link returned in the answer.
    103 
    104 Its parameters are:
    105 
    106     Parameter           Mandatory
    107     ------------        ------------
    108     accessRules         Yes
    109 
    110 The `accessRules` parameter is an ARRAY of HASHes. Each hash contains these keys:
    111 
    112 - method: an HTTP method among GET, POST, PUT and DELETE. ALL is a special values that includes all the methods;
    113 - 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.
    114 
    115 ### Example
    116 
    117     my $Api = OvhApi->new(type => OvhApi::OVH_API_EU, applicationKey => $AK, applicationSecret => $AS, consumerKey => $CK);
    118     my $Answer = $Api->requestCredentials(accessRules => [ { method => 'ALL', path => '/*' }]);
    119 
    120     if ($Answer)
    121     {
    122         my ($consumerKey, $validationUrl) = @{ $Answer->content}{qw{ consumerKey validationUrl }};
    123 
    124         # $consumerKey contains the newly created  Consumer Key
    125         # $validationUrl contains a link to OVH website in order to login an OVH account and link it to the credential
    126     }
    127 
    128 # SEE ALSO
    129 
    130 The guts of module are using: `LWP::UserAgent`, `JSON`, `Digest::SHA1`.
    131 
    132 # COPYRIGHT
    133 
    134 Copyright (c) 2013, OVH SAS.
    135 All rights reserved.
    136 
    137 This library is distributed under the terms of `LICENSE`.