https://github.com/ovh/node-ovh
Node.js wrapper for the OVH APIs
https://github.com/ovh/node-ovh
api-wrapper
Last synced: 9 months ago
JSON representation
Node.js wrapper for the OVH APIs
- Host: GitHub
- URL: https://github.com/ovh/node-ovh
- Owner: ovh
- License: other
- Created: 2014-09-22T14:20:22.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2025-04-16T15:48:25.000Z (10 months ago)
- Last Synced: 2025-05-15T09:18:02.997Z (9 months ago)
- Topics: api-wrapper
- Language: JavaScript
- Homepage: http://ovh.github.io/node-ovh
- Size: 832 KB
- Stars: 137
- Watchers: 35
- Forks: 28
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://ovh.github.io/node-ovh)
The easiest way to use the [OVHcloud.com](https://www.ovhcloud.com) APIs in your [node.js](https://nodejs.org/) applications.
[](https://www.npmjs.org/package/ovh)
[](https://travis-ci.org/ovh/node-ovh)
[](https://coveralls.io/r/ovh/node-ovh?branch=master)
```js
// Create your first application tokens here: https://api.ovh.com/createToken/?GET=/me
var ovh = require('@ovhcloud/node-ovh')({
appKey: process.env.APP_KEY,
appSecret: process.env.APP_SECRET,
consumerKey: process.env.CONSUMER_KEY
});
ovh.request('GET', '/me', function (err, me) {
console.log(err || 'Welcome ' + me.firstname);
});
```
You can also use the promised version like this:
```js
ovh.requestPromised('GET', '/me')
.then(function (response) {
//Do what you want
})
.catch(function (err) {
//Return an error object like this {error: statusCode, message: message}
});
```
## Installation
The easiest way to get the latest stable release is to grab it from the
[npm registry](https://npmjs.org/package/@ovhcloud/node-ovh).
```bash
$ npm install @ovhcloud/node-ovh
```
Alternatively, you may get latest development version directly from Git.
```bash
$ npm install git://github.com/ovh/node-ovh.git
```
## Example Usage
### OAuth2
#### 1. Generate credentials
Generate a valid pair of clientID/clientSecret following this [documentation](https://help.ovhcloud.com/csm/en-manage-service-account?id=kb_article_view&sysparm_article=KB0059343)
#### 2. Create an OVHcloud API client
```js
var ovh = require('@ovhcloud/node-ovh')({
clientID: 'YOUR_CLIENT_ID'
clientSecret: 'YOUR_CLIENT_SECRET'
endpoint: 'ovh-eu',
});
```
Depending on the API you want to use, you may set the endpoint to:
* `ovh-eu` for OVHcloud Europe API
* `ovh-us` for OVHcloud US API
* `ovh-ca` for OVHcloud Canada API
### Application Key/ApplicationSecret
#### 1. Create an application
Depending the API you plan to use, you need to create an application on the below
websites:
* [OVHcloud Europe](https://eu.api.ovh.com/createApp/)
* [OVHcloud US](https://api.us.ovhcloud.com/createApp/)
* [OVHcloud North-America](https://ca.api.ovh.com/createApp/)
* [SoYouStart Europe](https://eu.api.soyoustart.com/createApp/)
* [SoYouStart North-America](https://ca.api.soyoustart.com/createApp/)
* [Kimsufi Europe](https://eu.api.kimsufi.com/createApp/)
* [Kimsufi North-America](https://ca.api.kimsufi.com/createApp/)
Once created, you will obtain an **application key (AK)** and an **application
secret (AS)**.
#### 2. Authorize your application to access to a customer account
To allow your application to access to a customer account using an OVHcloud API,
you need a **consumer key (CK)**.
Here is a sample code you can use to allow your application to access to a
complete account.
Depending the API you want to use, you need to specify the below API endpoint:
* OVHcloud Europe: ```ovh-eu``` (default)
* OVHcloud US: ```ovh-us```
* OVHcloud North-America: ```ovh-ca```
* SoYouStart Europe: ```soyoustart-eu```
* SoYouStart North-America: ```soyoustart-ca```
* Kimsufi Europe: ```kimsufi-eu```
* Kimsufi North-America: ```kimsufi-ca```
```js
var ovh = require('@ovhcloud/node-ovh')({
endpoint: 'ovh-eu',
appKey: 'YOUR_APP_KEY',
appSecret: 'YOUR_APP_SECRET'
});
ovh.request('POST', '/auth/credential', {
'accessRules': [
{ 'method': 'GET', 'path': '/*'},
{ 'method': 'POST', 'path': '/*'},
{ 'method': 'PUT', 'path': '/*'},
{ 'method': 'DELETE', 'path': '/*'}
]
}, function (error, credential) {
console.log(error || credential);
});
```
```bash
$ node credentials.js
{ validationUrl: 'https://api.ovh.com/auth/?credentialToken=XXX',
consumerKey: 'CK',
state: 'pendingValidation' }
```
This consumer key can be scoped with a **specific authorization**.
For example if your application will only send SMS:
```javascript
ovh.request('POST', '/auth/credential', {
'accessRules': [
{ 'method': 'POST', 'path': '/sms/*/jobs'},
]
}, function (error, credential) {
console.log(error || credential);
});
```
Once the consumer key will be authorized on the specified URL,
you'll be able to play with the API calls allowed by this key.
#### 3. Let's play!
You are now be able to play with the API. Look at the
[examples available online](https://ovh.github.io/node-ovh#examples).
You can browse the API schemas using the web consoles of the APIs:
* [OVHcloud Europe](https://eu.api.ovh.com/console/)
* [OVHcloud US](https://api.us.ovhcloud.com/console/)
* [OVHcloud North-America](https://ca.api.ovh.com/console/)
* [SoYouStart Europe](https://eu.api.soyoustart.com/console/)
* [SoYouStart North-America](https://ca.api.soyoustart.com/console/)
* [Kimsufi Europe](https://eu.api.kimsufi.com/console/)
* [Kimsufi North-America](https://ca.api.kimsufi.com/console/)
## Migration from 1.x.x to 2.x.x without Proxy support
For example if you use the OVHcloud Europe API, you'll have to check on https://eu.api.ovh.com/console/ the endpoints available for your feature.
In order to have the informations about the bill with id "0123".
+ Before in 1.x.x with Proxy:
```javascript
ovh.me.bill["0123"].$get(function (err, billInformation) {
});
```
+ Now in 2.x.x with promise:
```javascript
ovh.requestPromised('GET', '/me/bill/0123') //This route has been found at https://eu.api.ovh.com/console/
.then(function (billInformation) {
})
.catch(function (err) {
});
```
## Full documentation and examples
The full documentation is available online: https://ovh.github.io/node-ovh.
## Hacking
### Get the sources
```bash
git clone https://github.com/ovh/node-ovh.git
cd node-ovh
```
You've developed a new cool feature? Fixed an annoying bug? We'd be happy
to hear from you!
### Run the tests
Tests are based on [mocha](https://mochajs.org/).
This package includes unit and integration tests.
```
git clone https://github.com/ovh/node-ovh.git
cd node-ovh
npm install -d
npm test
```
Integration tests use the OVHcloud /domain/zone API, the tokens can be created
[here](https://api.ovh.com/createToken/).
```
export APP_KEY=xxxxx
export APP_SECRET=yyyyy
export CONSUMER_KEY=zzzzz
export DOMAIN_ZONE_NAME=example.com
npm run-script test-integration
```
### Documentation
The documentation is based on [Github Pages](https://pages.github.com/) and is
available in the *gh-pages* branch.
## Supported APIs
### OVHcloud 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/
### OVHcloud 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/
### OVHcloud 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/
### SoYouStart 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/
### SoYouStart 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/
## Related links
- **Contribute**: https://github.com/ovh/node-ovh
- **Report bugs**: https://github.com/ovh/node-ovh/issues
- **Download**: https://npmjs.org/package/ovh