JavaScript client for UpCloud's API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.swagger-codegen
docs
src
test
.babelrc
.gitignore
.npmignore
.swagger-codegen-ignore
.travis.yml
LICENSE
README.md
package-lock.json
package.json
yarn.lock

README.md

UpCloud JavaScript API client library

Build Status npm version License Coverage Status

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.