@upcloud/upcloud

    1.0.2 • Public • Published

    UpCloud JavaScript API client library

    Build Status npm version License

    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.

    Install

    npm i @upcloud/upcloud

    DownloadsWeekly Downloads

    10

    Version

    1.0.2

    License

    MIT

    Last publish

    Collaborators

    • peknur
    • darep
    • vaykka666
    • jgabor
    • jpjp
    • iivari.leinonen
    • trdls
    • bachirkhiati-upcloud
    • touko-uc
    • matiasupcloud
    • kamilcybulski