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
Node.js
Fornpm
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
- upcloud.Account
- upcloud.AccountResponse
- upcloud.AddIpRequest
- upcloud.AddressFamily
- upcloud.AssignIpResponse
- upcloud.AttachStorageDeviceRequest
- upcloud.AvailablePlanListResponse
- upcloud.AvailablePlanListResponsePlans
- upcloud.BackupRule
- upcloud.CloneStorageRequest
- upcloud.ConfigurationListResponse
- upcloud.ConfigurationListResponseServerSizes
- upcloud.CreateBackupStorageRequest
- upcloud.CreateNewTagResponse
- upcloud.CreateServerRequest
- upcloud.CreateServerResponse
- upcloud.CreateStorageRequest
- upcloud.CreateStorageResponse
- upcloud.Error
- upcloud.ErrorCode
- upcloud.ErrorError
- upcloud.ErrorStatus
- upcloud.FirewallRule
- upcloud.FirewallRuleCreateResponse
- upcloud.FirewallRuleListResponse
- upcloud.FirewallRuleListResponseFirewallRules
- upcloud.FirewallRuleRequest
- upcloud.IpAddress
- upcloud.IpAddressListResponse
- upcloud.IpAddresses
- upcloud.ModifyIpRequest
- upcloud.ModifyStorageRequest
- upcloud.ModifyTagRequest
- upcloud.Plan
- upcloud.Price
- upcloud.PriceListResponse
- upcloud.PriceListResponsePrices
- upcloud.PriceZone
- upcloud.RestartServer
- upcloud.Server
- upcloud.ServerListResponse
- upcloud.ServerListResponseServers
- upcloud.ServerSize
- upcloud.ServerState
- upcloud.ServerStorageDevices
- upcloud.ServerTags
- upcloud.StopServer
- upcloud.StopServerRequest
- upcloud.Storage
- upcloud.StorageAccessType
- upcloud.StorageBackups
- upcloud.StorageDevice
- upcloud.StorageDeviceDetachRequest
- upcloud.StorageDeviceLoadRequest
- upcloud.StorageServers
- upcloud.StorageState
- upcloud.StorageTier
- upcloud.StorageType
- upcloud.SuccessStoragesResponse
- upcloud.SuccessStoragesResponseStorages
- upcloud.Tag
- upcloud.TagCreateRequest
- upcloud.TagListResponse
- upcloud.TagListResponseTags
- upcloud.TagServers
- upcloud.TemplitizeStorageRequest
- upcloud.Timezone
- upcloud.TimezoneListResponse
- upcloud.TimezoneListResponseTimezones
- upcloud.Zone
- upcloud.ZoneListResponse
- upcloud.ZoneListResponseZones
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.