node-ovh

To use the OVH API, you must instantiate the client by providing authentication credentials. The client supports two main authentication methods: Legacy Application Key and OAuth2. You cannot use both simultaneously.

Authentication Options

1. Legacy Application Key/Secret: Requires appKey and appSecret. If you also have a consumerKey, provide it to enable request signing.
2. OAuth2: Requires clientID, clientSecret, and a tokenURL.

Configuration Parameters

const ovh = require('node-ovh');

// Example using Application Key/Secret
const client = ovh({
  appKey: 'YOUR_APP_KEY',
  appSecret: 'YOUR_APP_SECRET',
  consumerKey: 'YOUR_CONSUMER_KEY'
});

// Example using OAuth2
const oauthClient = ovh({
  clientID: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  tokenURL: 'https://auth.ovh.com/oauth2/token'
});

The library provides two ways to make API requests: a callback-based method request() and a Promise-based method requestPromised().

Callback pattern

Use request(method, path, [body], callback) where the callback receives (err, response).

Promise pattern

Use requestPromised(method, path, [body]) which returns a Promise that resolves with the response or rejects with an error object in the format {error: statusCode, message: message}.

var ovh = require('@ovhcloud/node-ovh')({
  appKey: process.env.APP_KEY,
  appSecret: process.env.APP_SECRET,
  consumerKey: process.env.CONSUMER_KEY
});

// Callback usage
ovh.request('GET', '/me', function (err, me) {
  console.log(err || 'Welcome ' + me.firstname);
});

// Promise usage
ovh.requestPromised('GET', '/me')
  .then(function (response) {
    // Do what you want
  })
  .catch(function (err) {
    // Handle error
  });

The requestPromised method is the recommended way to interact with the OVH API using modern async/await syntax. It returns a Bluebird promise.

Parameters:

• httpMethod: The HTTP verb (e.g., 'GET', 'POST', 'PUT', 'DELETE').
• path: The API endpoint path. Supports template placeholders like {paramName} which will be replaced by values in the params object.
• params: An object containing query string parameters or the JSON body (for POST/PUT).

Note: If the path contains {key}, the corresponding value in params is extracted from the body and injected into the URL path.

// Example: GET request with query params
const services = await client.requestPromised('GET', '/services', { limit: 10 });

// Example: POST request with body
const result = await client.requestPromised('POST', '/services', { name: 'new-service' });

// Example: Path parameter replacement
// If path is '/services/{id}', passing { id: '123' } results in '/services/123'
const service = await client.requestPromised('GET', '/services/{id}', { id: '123' });

The request method is the primary way to interact with the OVH API. It supports path parameter replacement using the {key} syntax.

Signature: request(httpMethod, path, params, callback)

• httpMethod: The HTTP verb (e.g., 'GET', 'POST', 'PUT', 'DELETE').
• path: The API endpoint path. If the path contains placeholders like {id}, the values in params will be used to replace them.
• params: An object containing query string parameters (for GET) or the request body (for POST/PUT).
• callback: A function called with (error, response). If error is present, it may be a status code or an error object.

Note on Path Parameters: If a parameter in params is used to replace a placeholder in the path, it is automatically removed from the params object so it is not sent in the body or query string.

client.request('GET', '/user/{id}', { id: '123' }, function (err, resp) {
  if (err) return console.error(err);
  console.log(resp);
});

The node-ovh library provides a set of preconfigured endpoint configurations for different OVHcloud services and regions. These configurations include the API host and, where applicable, the tokenURL required for authentication. You can use these identifiers to quickly target specific services like OVH Europe, OVH US, SoYouStart, or Kimsufi.

// Available endpoint identifiers and their configurations:
{
  'ovh-eu': { 'host': 'eu.api.ovh.com', 'tokenURL': 'https://www.ovh.com/auth/' },
  'ovh-us': { 'host': 'api.us.ovhcloud.com', 'tokenURL': 'https://us.ovhcloud.com/auth/' },
  'ovh-ca': { 'host': 'ca.api.ovh.com', 'tokenURL': 'https://ca.ovh.com/auth/' },
  'sys-eu': { 'host': 'eu.api.soyoustart.com' },
  'sys-ca': { 'host': 'ca.api.soyoustart.com' },
  'soyoustart-eu': { 'host': 'eu.api.soyoustart.com' },
  'soyoustart-ca': { 'host': 'ca.api.soyoustart.com' },
  'ks-eu': { 'host': 'eu.api.kimsufi.com' },
  'ks-ca': { 'host': 'ca.api.kimsufi.com' },
  'kimsufi-eu': { 'host': 'eu.api.kimsufi.com' },
  'kimsufi-ca': { 'host': 'eu.api.kimsufi.com' }
}