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