crystal-ovh

Lightweight Crystal wrapper around OVH's APIs. Handles all the hard work including credential creation and requests signing.

Installation

Add this to your application's shard.yml:

dependencies:
  ovh:
    github: ovh/crystal-ovh

Usage

require "ovh"

begin
  client = Ovh::Client.new("ovh-eu", "<key>", "<secret>", "<consumer_key>")
  client.get("/cloud/project").each do |id|
    puts "Project id : #{id}"
  end
rescue err : Ovh::RequestFailed
  puts "Error raised : #{err}"
end

Getting application credentials

1. Create an application

To interact with APIs of a particular OVH service, your application needs to identify itself using an application key and an application secret. To get them, you need to register your application.

Depending on the service you plan to use, visit:

• OVH Europe
• OVH North America
• SoyouStart Europe
• SoyouStart North America
• Kimsufi Europe
• Kimsufi North America
• RunAbove

2. Configure your application

In order to configure your application you can either :

• Use credentials direclty as literals.
• Use environment variables.
• Use a configuration file.

The easiest and safest way to use your application's credentials is to create an ovh.conf file :

[default]
; general configuration: default endpoint
endpoint=ovh-eu

[ovh-eu]
; configuration specific to 'ovh-eu' endpoint
application_key=my_app_key
application_secret=my_app_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-ca for OVH North-America API
• soyoustart-eu for So you Start Europe API
• soyoustart-ca for So you Start North America API
• kimsufi-eu for Kimsufi Europe API
• kimsufi-ca for Kimsufi North America API
• runabove-ca for RunAbove API

The configuration loader will try to find this configuration file in multiple places. Lookups are achieved in the following order :

1. Current working directory: ./ovh.conf
2. Current user's home directory ~/.ovh.conf
3. System wide configuration /etc/ovh.conf

If you decide to hold your configuration in the environment, the following variables are expected :

• OVH_ENDPOINT
• OVH_APPLICATION_KEY
• OVH_APPLICATION_SECRET
• OVH_CONSUMER_KEY

This configuration will be shared by all applications.

Now you can use :

  # Using a specific endpoint
  client = Ovh::Client.new("ovh-eu")

Or

  # Using default endpoint
  client = Ovh::Client.new()

3. Authorize your application

To allow your application to access a customer account using the API on your behalf, you need a consumer key. When requesting this consumer key, you can set access rules to certain request paths.

Here is an example :

require "ovh"

begin
  # Create an application from configuration
  client = Ovh::Client.new("ovh-eu")

  # Allow GET and POST & PUT requests for all "/cloud" calls
  ck_req = client.consumer_request()
  ck_req.add_rule("/cloud/*", Ovh::Rule::Read | Ovh::Rule::Write)

  # Allow DELETE requests for all "/domain" calls
  ck_req.add_rule("/domain/*", Ovh::Rule::Delete)

  # Register this application as a consumer.
  ck_req.execute() do |ck_rep|
    puts "Application consumer key is #{ck_rep.consumer_key}"
    puts "Visit #{ck_rep.validation_url} to activate it and press enter to continue..."
    gets
  end
rescue err: Ovh::ConfigurationError | Ovh::RequestFailed
  puts "Error raised : #{err}"
end

Returned consumer key should then be saved in your configuration to avoid re-authenticating your end-user on each use.

Hacking

Make sure to use the latest version of crystal and to follow the contribution guidelines.

Code formatting

Code must be formatted with crystal tool format.

Tests

If you develop a new feature, you must write tests for it. These are located in the spec/ directory.

You can run them with crystal spec -v.

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 North America

• 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 North America

• 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 North America

• 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/

RunAbove

• Community support: https://community.runabove.com/
• Console: https://api.runabove.com/console/
• Create application credentials: https://api.runabove.com/createApp/
• High level SDK: https://github.com/runabove/python-runabove

License

3-Clause BSD