@upcloud/upcloud

v1.0.2

Published

5 months ago

The JavaScript SDK for UpCloud's API

Downloads

0High
0Medium
0Low

upcloud cloud wrapper api babel es6

UpCloud JavaScript API client library

This is a Javascript API client library that provides integration with the UpCloud API. It allows cloud resource management on UpCloud's IaaS with easy to use functions. The API client follows the RESTful web service principles wherever possible.

The base URL for all API operations is https://api.upcloud.com/ and require basic authentication using UpCloud username and password. We recommend creating a subaccount dedicated for the API communication for security purposes. This allows you to restrict API access by servers, storages, and tags ensuring you will never accidentally affect critical systems.

Table of content

Installation

For Node.js

npm

Install it via:

npm install @upcloud/upcloud --save

Local development

To use the library locally without publishing to a remote npm registry, first install the dependencies by changing into the directory containing package.json (and this README). Let's call this JAVASCRIPT_CLIENT_DIR. Then run:

npm install

Next, link it globally in npm with the following, also from JAVASCRIPT_CLIENT_DIR:

npm link

Finally, switch to the directory you want to use your upcloud from, and run:

npm link /path/to/<JAVASCRIPT_CLIENT_DIR>

You should now be able to require('upcloud') in javascript files from the directory you ran the last command above from.

git

Install the library via git:

    npm install UpCloudLtd/upcloud-javascript-api --save

For browser

The library also works in the browser environment via npm and browserify. After following the above steps with Node.js and installing browserify with npm install -g browserify, perform the following (assuming main.js is your entry file, that's to say your javascript file where you actually use this library):

browserify main.js > bundle.js

Then include bundle.js in the HTML pages.

Webpack Configuration

Using Webpack you may encounter the following error: "Module not found: Error: Cannot resolve module", most certainly you should disable AMD loader. Add/merge the following section to your webpack config:

module: {
  rules: [
    {
      parser: {
        amd: false
      }
    }
  ]
}

Usage

Please follow the installation instruction and execute the following JS code (NOTE: In real production applications you should use for example ENV variables instead of inserting credentials directly to code and to version control):

var upcloud = require('upcloud');

var defaultClient = upcloud.ApiClient.instance;

// Configure HTTP basic authorization: baseAuth
var baseAuth = defaultClient.authentications['baseAuth'];
baseAuth.username = 'UPCLOUD_USERNAME'
baseAuth.password = 'UPCLOUD_PASSWORD'

var api = new upcloud.AccountApi()
api.getAccount().then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Documentation

All URIs are relative to https://api.upcloud.com/1.2

Class | Method | HTTP request | Description ------------ | ------------- | ------------- | ------------- upcloud.AccountApi | getAccount | GET /account | Account information upcloud.FirewallApi | createFirewallRule | POST /server/{serverId}/firewall_rule | Create firewall rule upcloud.FirewallApi | deleteFirewallRule | DELETE /server/{serverId}/firewall_rule/{firewallRuleNumber} | Remove firewall rule upcloud.FirewallApi | getFirewallRule | GET /server/{serverId}/firewall_rule/{firewallRuleNumber} | Get firewall rule details upcloud.FirewallApi | serverServerIdFirewallRuleGet | GET /server/{serverId}/firewall_rule | List firewall rules upcloud.IPAddressApi | addIp | POST /ip_address | Assign IP address upcloud.IPAddressApi | deleteIp | DELETE /ip_address/{ip} | Release IP address upcloud.IPAddressApi | getDetails | GET /ip_address/{ip} | Get IP address details upcloud.IPAddressApi | listIps | GET /ip_address | List IP addresses upcloud.IPAddressApi | modifyIp | PUT /ip_address/{ip} | Modify IP address upcloud.PlanApi | listPlans | GET /plan | List available plans upcloud.PricesApi | listPrices | GET /price | List prices upcloud.ServerApi | assignTag | POST /server/{serverId}/tag/{tagList} | Assign tag to a server upcloud.ServerApi | attachStorage | POST /server/{serverId}/storage/attach | Attach storage upcloud.ServerApi | createFirewallRule | POST /server/{serverId}/firewall_rule | Create firewall rule upcloud.ServerApi | createServer | POST /server | Create server upcloud.ServerApi | deleteFirewallRule | DELETE /server/{serverId}/firewall_rule/{firewallRuleNumber} | Remove firewall rule upcloud.ServerApi | deleteServer | DELETE /server/{serverId} | Delete server upcloud.ServerApi | detachStorage | POST /server/{serverId}/storage/detach | Detach storage upcloud.ServerApi | ejectCdrom | POST /server/{serverId}/cdrom/eject | Eject CD-ROM upcloud.ServerApi | getFirewallRule | GET /server/{serverId}/firewall_rule/{firewallRuleNumber} | Get firewall rule details upcloud.ServerApi | listServerConfigurations | GET /server_size | List server configurations upcloud.ServerApi | listServers | GET /server | List of servers upcloud.ServerApi | loadCdrom | POST /server/{serverId}/storage/cdrom/load | Load CD-ROM upcloud.ServerApi | modifyServer | PUT /server/{serverId} | Modify server upcloud.ServerApi | restartServer | POST /server/{serverId}/restart | Restart server upcloud.ServerApi | serverDetails | GET /server/{serverId} | Get server details upcloud.ServerApi | serverServerIdFirewallRuleGet | GET /server/{serverId}/firewall_rule | List firewall rules upcloud.ServerApi | startServer | POST /server/{serverId}/start | Start server upcloud.ServerApi | stopServer | POST /server/{serverId}/stop | Stop server upcloud.ServerApi | untag | POST /server/{serverId}/untag/{tagName} | Remove tag from server upcloud.StorageApi | attachStorage | POST /server/{serverId}/storage/attach | Attach storage upcloud.StorageApi | backupStorage | POST /storage/{storageId}/backup | Create backup upcloud.StorageApi | cancelOperation | POST /storage/{storageId}/cancel | Cancel storage operation upcloud.StorageApi | cloneStorage | POST /storage/{storageId}/clone | Clone storage upcloud.StorageApi | createStorage | POST /storage | Create storage upcloud.StorageApi | deleteStorage | DELETE /storage/{storageId} | Delete storage upcloud.StorageApi | detachStorage | POST /server/{serverId}/storage/detach | Detach storage upcloud.StorageApi | ejectCdrom | POST /server/{serverId}/cdrom/eject | Eject CD-ROM upcloud.StorageApi | favoriteStorage | POST /storage/{storageId}/favorite | Add storage to favorites upcloud.StorageApi | getStorageDetails | GET /storage/{storageId} | Get storage details upcloud.StorageApi | listStorageTypes | GET /storage/{type}/ | List of storages by type upcloud.StorageApi | listStorages | GET /storage | List of storages upcloud.StorageApi | loadCdrom | POST /server/{serverId}/storage/cdrom/load | Load CD-ROM upcloud.StorageApi | modifyStorage | PUT /storage/{storageId} | Modify storage upcloud.StorageApi | restoreStorage | POST /storage/{storageId}/restore | Restore backup upcloud.StorageApi | templatizeStorage | POST /storage/{storageId}/templatize | Templatize storage upcloud.StorageApi | unfavoriteStorage | DELETE /storage/{storageId}/favorite | Remove storage from favorites upcloud.TagApi | assignTag | POST /server/{serverId}/tag/{tagList} | Assign tag to a server upcloud.TagApi | createTag | POST /tag | Create a new tag upcloud.TagApi | deleteTag | DELETE /tag/{tagName} | Delete tag upcloud.TagApi | listTags | GET /tag | List existing tags upcloud.TagApi | modifyTag | PUT /tag/{tagName} | Modify existing tag upcloud.TagApi | untag | POST /server/{serverId}/untag/{tagName} | Remove tag from server upcloud.TimezoneApi | listTimezones | GET /timezone | List timezones upcloud.ZoneApi | listZones | GET /zone | List available zones

Documentation of the models

Documentation for authorization

Take care if storing usernames or passwords in files while developing API applications to avoid accidentally publishing your account credentials.

baseAuth

Type: HTTP basic authentication
Username: Your UpCloud API username
Password: Your UpCloud API user's password

Issues

Found a bug, have a problem using the client, or anything else about the library you would want to mention? Open a new issue here to get in contact.

License

This project is distributed under the MIT License, see LICENSE.txt for more information.