perl-ovh ======== Perl wrapper around OVH's APIs. Handles all the hard work including credential creation and requests signing. ## Synopsis ```perl #!/usr/bin/env perl use strict; use warnings; use OvhApi; my $ApiOvh = OvhApi->new( timeout => 10, ); my $identity = $ApiOvh->get(path => "/me"); if (!$identity) { printf("Failed to retrieve identity: %s\n", $identity); return 0; } $identity = $identity->content(); printf("Welcome %s\n", $identity->{'firstname'}); ``` ## Installation ``` perl Makefile.PL make make test make install ``` ## Register your app OVH's API, like most modern APIs is designed to authenticate both an application and a user, without requiring the user to provide a password. Your application will be identified by its "application secret" and "application key" tokens. Hence, to use the API, you must first register your application and then ask your user to authenticate on a specific URL. Once authenticated, you'll have a valid "consumer key" which will grant your application on specific APIs. The user may choose the validity period of its authorization. The default period is 24h. He may also revoke an authorization at any time. Hence, your application should be prepared to receive 403 HTTP errors and prompt the user to re-authenticated. This process is detailed in the following section. Alternatively, you may only need to build an application for a single user. In this case you may generate all credentials at once. See below. ### Use the API on behalf of a user Visit [https://eu.api.ovh.com/createApp](https://eu.api.ovh.com/createApp) and create your app You'll get an application key and an application secret. To use the API you'll need a consumer key. The consumer key has two types of restriction: * path: eg. only the ```GET``` method on ```/me``` * time: eg. expire in 1 day Then, get a consumer key. ### Use the API for a single user Alternatively, you may generate all creadentials at once, including the consumer key. You will typically want to do this when writing automation scripts for a single projects. If this case, you may want to directly go to https://eu.api.ovh.com/createToken/ to generate the 3 tokens at once. ## Configuration The straightforward way to use OVH's API keys is to embed them directly in the application code. While this is very convenient, it lacks of elegance and flexibility. You might also need to add your scripts into some source control systems, and adding credentials into source control is not the best way to manage your credentials. `perl-ovh` will look for a configuration file of the form: ```ini [default] ; general configuration: default endpoint endpoint=ovh-eu [ovh-eu] ; configuration specific to 'ovh-eu' endpoint application_key=my_app_key application_secret=my_application_secret consumer_key=my_consumer_key ``` Depending on the API you want to use, you may set the ``endpoint`` to: * ``ovh-eu`` for OVH Europe API * ``ovh-us`` for OVH US API * ``ovh-ca`` for OVH Canada API * ``soyoustart-eu`` for So you Start Europe API * ``soyoustart-ca`` for So you Start Canada API * ``kimsufi-eu`` for Kimsufi Europe API * ``kimsufi-ca`` for Kimsufi Canada API The client will successively attempt to locate this configuration file in 1. Current working directory: ``./ovh.conf`` 2. Current user's home directory ``~/.ovh.conf`` 3. System wide configuration ``/etc/ovh.conf`` This lookup mechanism makes it easy to overload credentials for a specific project or user. ## Usage ```perl #!/usr/bin/env perl use strict; use warnings; use 5.010; use OvhApi; sub main { my $ApiOvh = OvhApi->new( timeout => 10, ); if (not $ApiOvh->{consumerKey}) { my $validation = $ApiOvh->requestCredentials( accessRules => [ { method => "ALL", path => "/hosting/web*", }, { method => "GET", path => "/me", }, ] ); if (not $validation) { printf("Failed to request new credentials: %s\n", $validation); return 0; } $validation = $validation->content(); printf("Please visit %s to authenticate,\nand press Enter to continue...", $validation->{'validationUrl'}); // die "Abort.\n"; $ApiOvh->{consumerKey} = $validation->{'consumerKey'}; printf("Your 'consumerKey' is '%s', you can save it to use it next time you want to use this script!\n", $ApiOvh->{'consumerKey'}); } my $identity = $ApiOvh->get(path => "/me"); if (!$identity) { printf("Failed to retrieve identity: %s\n", $identity); return 0; } $identity = $identity->content(); printf("Welcome %s\n", $identity->{'firstname'}); print("Listing all web hosting products...\n"); my $hostingWebList = $ApiOvh->get( path => '/hosting/web', ); if (not $hostingWebList) { printf("Error: %s\n", $hostingWebList); return 0; } $hostingWebList = $hostingWebList->content; if (not @$hostingWebList) { print("You don't have any web hosting on your account!\n"); return 0; } print("Available web hosting:\n"); foreach my $hostingWeb (@$hostingWebList) { printf("- %s\n", $hostingWeb); } printf("\nRenaming %s\nEnter a new name: ", $hostingWebList->[0]); my $newName = // die "Abort.\n"; chomp $newName; my $renamingOperation = $ApiOvh->put( path => "/hosting/web/".$hostingWebList->[0], body => { displayName => $newName, }, ); if (not $renamingOperation) { printf("Error while renaming: %s\n", $renamingOperation); return 0; } print("Renamed successfully!\n"); } main(); ``` ## Hacking This wrapper uses standard Perl tools, so you should feel at home with it. You've developed a new cool feature ? Fixed an annoying bug ? We'd be happy to hear from you ! See [CONTRIBUTING.md](https://github.com/ovh/perl-ovh/blob/master/CONTRIBUTING.md) for more informations ## Supported APIs ### OVH Europe - **Documentation**: https://eu.api.ovh.com/ - **Community support**: api-subscribe@ml.ovh.net - **Console**: https://eu.api.ovh.com/console - **Create application credentials**: https://eu.api.ovh.com/createApp/ - **Create script credentials** (all keys at once): https://eu.api.ovh.com/createToken/ ### OVH US - **Documentation**: https://api.us.ovhcloud.com/ - **Console**: https://api.us.ovhcloud.com/console/ - **Create application credentials**: https://api.us.ovhcloud.com/createApp/ - **Create script credentials** (all keys at once): https://api.us.ovhcloud.com/createToken/ ### OVH Canada - **Documentation**: https://ca.api.ovh.com/ - **Community support**: api-subscribe@ml.ovh.net - **Console**: https://ca.api.ovh.com/console - **Create application credentials**: https://ca.api.ovh.com/createApp/ - **Create script credentials** (all keys at once): https://ca.api.ovh.com/createToken/ ### So you Start Europe - **Documentation**: https://eu.api.soyoustart.com/ - **Community support**: api-subscribe@ml.ovh.net - **Console**: https://eu.api.soyoustart.com/console/ - **Create application credentials**: https://eu.api.soyoustart.com/createApp/ - **Create script credentials** (all keys at once): https://eu.api.soyoustart.com/createToken/ ### So you Start Canada - **Documentation**: https://ca.api.soyoustart.com/ - **Community support**: api-subscribe@ml.ovh.net - **Console**: https://ca.api.soyoustart.com/console/ - **Create application credentials**: https://ca.api.soyoustart.com/createApp/ - **Create script credentials** (all keys at once): https://ca.api.soyoustart.com/createToken/ ### Kimsufi Europe - **Documentation**: https://eu.api.kimsufi.com/ - **Community support**: api-subscribe@ml.ovh.net - **Console**: https://eu.api.kimsufi.com/console/ - **Create application credentials**: https://eu.api.kimsufi.com/createApp/ - **Create script credentials** (all keys at once): https://eu.api.kimsufi.com/createToken/ ### Kimsufi Canada - **Documentation**: https://ca.api.kimsufi.com/ - **Community support**: api-subscribe@ml.ovh.net - **Console**: https://ca.api.kimsufi.com/console/ - **Create application credentials**: https://ca.api.kimsufi.com/createApp/ - **Create script credentials** (all keys at once): https://ca.api.kimsufi.com/createToken/ ## License 3-Clause BSD