A Javascript client for the UpCloud API
- Installing
upcloud-api
- Including
upcloud-api
in your scripts/applications - Initialisation
- Scope and Roadmap
- Invoking the API
- Commands
- Dependencies
- Copyright and License
upcloud-api
is available as a Node module on npmjs.com and can simply be installed with:
npm install upcloud-api
To use upcloud-api
you need to include it in your scripts:
const uc = require("upcloud-api");
Or, if you aren't installing with npm
, you can simply clone this repository and directly reference upcloud-api.js
:
const uc = require("/path/to/upcloud-api.js");
To initialise upcloud-api
you need an UpCloud username and password for an account or subaccount with permission to access the UpCloud API. You can learn more about creating accounts with API permission in Upcloud's documentation.
Once you have the appropriate username and password you can initialise upcloud-api
with:
uc.init(USERNAME_GOES_HERE,PASSWORD_GOES_HERE);
This is an early pre-release of upcloud-api
with some limitations:
- There is no error handling yet in
upcloud-api
so if you fail to authenticate, fail to connect to the UpCloud API or there is an error in the data passed to the API,upcloud-api
may fail without any error handling and your script will terminate with an error.
This version currently uses version 1.3 of the UpCloud API.
All interaction with the API through upcloud-api
is done through the call
method of upcloud-api
. The syntax for the call
method is:
uc.call(COMMAND_NAME, PARAMETERS, POST_DATA, CALLBACK_FUNCTION);
The four arguments are:
COMMAND_NAME
: The name of anupcloud-api
command as discussed below.PARAMETERS
: An object containing one or more parameters required by the command being invoked.DATA
: An object containing data to be sent as JSON in a POST request to the UpCloud API for commands which require POST requests with JSON data in the body of the request. To determine what data to send in a POST request, refer to the UpCloud API documentation.CALLBACK_FUNCTION
: A function to invoke when the UpCloud API responds to the command. Three arguments will be sent to a single function containing the JSON object returned by the UpCloud API.
For instance, to retrieve a list of servers you could use:
uc.call("listServers", {}, {}, (res) => {
console.log(res);
});
Or, to retrieve a server's specific details:
uc.call("serverDetails", { serveruuid: SERVER_UUID_HERE }, {}, (res) => {
console.log(res);
});
Or, to attach storage to a server:
uc.call("createServer", { serveruuid: SERVER_UUID_HERE }, {
storage_device": {
type: "disk",
address: "virtio",
storage: "STORAGE_RESOURCE_UUID_HERE",
boot_disk: 0
}
}, (res) => {
console.log(res);
});
Description: Request a list of available server configurations
UpCloud API Endpoint: https://api.upcloud.com/1.3/server_size
Request Type: GET
Parameters: None
Description: Requests a list of servers
UpCloud API Endpoint: https://api.upcloud.com/1.3/server
Request Type: GET
Parameters: None
Description: Request details of a specific server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server
Request Type: GET
Parameters:
serveruuid
: UUID for the server
Description: Create a new server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server
Request Type: POST
Parameters: None
POST Data: See the UpCloud API documentation
Description: Modify configuration of an existing server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server
Request Type: PUT
Parameters:
serveruuid
: UUID for the server
PUT Data: See the UpCloud API documentation
Description: Start a stopped server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/start
Request Type: POST
Parameters:
serveruuid
: UUID for the server
POST Data: See the UpCloud API documentation
Description: Stop a running server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/stop
Request Type: POST
Parameters:
serveruuid
: UUID for the server
POST Data: See the UpCloud API documentation
Description: Restart a running server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/restart
Request Type: POST
Parameters:
serveruuid
: UUID for the server
POST Data: See the UpCloud API documentation
Description: Cancel a running operation on a server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/cancel
Request Type: POST
Parameters:
serveruuid
: UUID for the server
POST Data: None
Description: Delete a stopped server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]?storages=[storageaction]&backups=[backupaction]
Request Type: DELETE
Parameters:
serveruuid
: UUID for the serverstorageaction
: Indicates whether to delete attached storage resources -- possible values are:0
orfalse
: Don't delete attached storage resources1
ortrue
: Delete attached storage resources
backupaction
: Indicates whether to keep backups of deleted storage resources -- possible values are:keep
: Keep all backupskeep_latest
: Keep latest backupdelete
: Delete backups
Description: Request details of a specific storage resources
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage
Request Type: GET
Parameters:
storageuuid
: UUID for the storage resource
Description: Requests a list of storage templates
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/template
Request Type: GET
Parameters: None
Description: Requests a list of active storage resources
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage
Request Type: GET
Parameters: None
Description: Requests a list of active storage resources by type
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[TYPE]
Request Type: GET
Parameters:
storagetype
: The type of storage resources to return in the list -- possible values are:public
private
normal
backups
cdrom
template
favorite
Description: Requests a list of available CDROM images
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/cdrom
Request Type: GET
Parameters: None
Description: Create a new storage resource
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/
Request Type: POST
Parameters: None
POST Data: See the UpCloud API documentation
Description: Change configuration of a storage resource
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]
Request Type: PUT
Parameters:
storageuuid
: UUID for the storage resource
PUT Data: See the UpCloud API documentation
Description: Clone a storage template to a new storage resource
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/clone
Request Type: POST
Parameters:
storageuuid
: UUID for the storage resource
POST Data: See the UpCloud API documentation
Description: Attach a storage resource to a server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/storage/attach
Request Type: POST
Parameters:
serveruuid
: UUID for the server
POST Data: See the UpCloud API documentation
Description: Detach a storage resource from a server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/storage/detach
Request Type: POST
Parameters:
serveruuid
: UUID for the server
POST Data: See the UpCloud API documentation
Description: Load a CDROM onto a server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/cdrom/load
Request Type: POST
Parameters:
serveruuid
: UUID for the server
POST Data: See the UpCloud API documentation
Description: Eject a CDROM from a server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/cdrom/eject
Request Type: POST
Parameters:
serveruuid
: UUID for the server
POST Data: See the UpCloud API documentation
Description: Import data into an existing storage resource
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/import
Request Type: POST
Parameters:
storageuuid
: UUID for the storage resource
POST Data: See the UpCloud API documentation
Description: Get details of an ongoing or completed storage import task
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/import
Request Type: GET
Parameters:
storageuuid
: UUID for the storage resource
Description: Cancel a running storage import task
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/import/cancel
Request Type: POST
Parameters:
storageuuid
: UUID for the storage resource
POST Data: See the UpCloud API documentation
Description: Cancel a running storage cloning operation
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/cancel
Request Type: POST
Parameters:
storageuuid
: UUID for the storage resource
POST Data: See the UpCloud API documentation
Description: Create a template from a storage resource
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/templatize
Request Type: POST
Parameters:
storageuuid
: UUID for the storage resource
POST Data: See the UpCloud API documentation
Description: Create a point-in-time backup of a storage resource
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/backup
Request Type: POST
Parameters:
storageuuid
: UUID for the storage resource
POST Data: See the UpCloud API documentation
Description: Restores a storage resource from its backup
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/restore
Request Type: POST
Parameters:
storageuuid
: UUID for the storage resource
POST Data: See the UpCloud API documentation
Description: Add a storage resource to the favorites list
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/favorite
Request Type: POST
Parameters:
storageuuid
: UUID for the storage resource
POST Data: See the UpCloud API documentation
Description: Remove a storage resource from the favorites list
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]/favorite
Request Type: DELETE
Parameters:
storageuuid
: UUID for the storage resource
Description: Delete a storage resource
UpCloud API Endpoint: https://api.upcloud.com/1.3/storage/[UUID]?backups=[backupaction]
Request Type: DELETE
Parameters:
storageuuid
: UUID for the storage resourcebackupaction
: Indicates whether to keep backups of deleted storage resources -- possible values are:keep
: Keep all backupskeep_latest
: Keep latest backupdelete
: Delete backups
Description: Retrieve a list of simple server plans
UpCloud API Endpoint: https://api.upcloud.com/1.3/plan
Request Type: GET
Parameters: None
Description: Retrieve a list of available zones
UpCloud API Endpoint: https://api.upcloud.com/1.3/zone
Request Type: GET
Parameters: None
Description: Retrieve a list of resource prices
UpCloud API Endpoint: https://api.upcloud.com/1.3/price
Request Type: GET
Parameters: None
Description: Retrieve basic information forthe current user's account or subaccount
UpCloud API Endpoint: https://api.upcloud.com/1.3/account
Request Type: GET
Parameters: None
Description: Retrieve list of accounts and subaccounts for current organisation
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/list
Request Type: GET
Parameters: None
Description: Retrieve details of a named account or subaccount
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/details/[USERNAME]
Request Type: GET
Parameters:
username
: The username of the account or subaccount
Description: Modify details of a named account or subaccount
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/details/[USERNAME]
Request Type: PUT
Parameters:
username
: The username of the account or subaccount
PUT Data: See the UpCloud API documentation
Description: Create a subaccount
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/sub
Request Type: POST
Parameters: None
POST Data: See the UpCloud API documentation
Description: Delete a named subaccount
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/sub/[USERNAME]
Request Type: DELETE
Parameters:
username
: The username of the subaccount
Description: Get a billing summary for a specified month
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/billing_summary/[YYYY]-[MM]
Request Type: GET
Parameters:
yyyy
: The four-digit year for the month being requestedmm
: The two-digit month (including leading zero if needed) for the month being requested
Description: Get a detailed billing report for a specified month
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/billing_summary/[YYYY]-[MM]/detailed
Request Type: GET
Parameters:
yyyy
: The four-digit year for the month being requestedmm
: The two-digit month (including leading zero if needed) for the month being requested
Description: Get a resource billing summary for a specified month for a specific resource
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/resource_billing_summary/[UUID]/[YYYY]-[MM]
Request Type: GET
Parameters:
resourceuuid
: The UUID of the resourceyyyy
: The four-digit year for the month being requestedmm
: The two-digit month (including leading zero if needed) for the month being requested
Description: Get network usage for a period of time
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/network_usage/?from=[FROM]&to=[TO]&accumulate=[DURATION]
Request Type: GET
Parameters:
from
: Timestamp for start of time period in RFC 3339 format (YYYY-MM-DDTHH:MM:SSZ)to
: Timestamp for end of time period in RFC 3339 format (YYYY-MM-DDTHH:MM:SSZ)duration
: Specifies time block for accumulating usage in the report -- possible values are:day
hour
Description: Get network usage for a specified resource for a period of time
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/resource_network_usage/?from=[FROM]&to=[TO]&accumulate=[DURATION]&resource_id=[UUID]
Request Type: GET
Parameters:
from
: Timestamp for start of time period in RFC 3339 format (YYYY-MM-DDTHH:MM:SSZ)to
: Timestamp for end of time period in RFC 3339 format (YYYY-MM-DDTHH:MM:SSZ)resourceuuid
: UUID for the resourceduration
: Specifies time block for accumulating usage in the report -- possible values are:day
hour
Description: Get latest network transfer pool usage report
UpCloud API Endpoint: https://api.upcloud.com/1.3/account/current_network_usage
Request Type: GET
Parameters: None
Description: Get list of IP addresses assigned to servers in the account
UpCloud API Endpoint: https://api.upcloud.com/1.3/ip_address
Request Type: GET
Parameters: None
Description: Get detailed information about a specific IP address
UpCloud API Endpoint: https://api.upcloud.com/1.3/ip_address/[ADDRESS]
Request Type: GET
Parameters:
address
: IP address such as127.0.0.1
Description: Assign a new IP address to a server
UpCloud API Endpoint: https://api.upcloud.com/1.3/ip_address
Request Type: POST
Parameters: None
POST Data: See the UpCloud API documentation
Description: Modify an IP address
UpCloud API Endpoint: https://api.upcloud.com/1.3/ip_address/[ADDRESS]
Request Type: PATCH
Parameters:
address
: IP address such as127.0.0.1
PATCH Data: See the UpCloud API documentation
Description: Release an IP address from a server
UpCloud API Endpoint: https://api.upcloud.com/1.3/ip_address/[ADDRESS]
Request Type: DELETE
Parameters:
address
: IP address such as127.0.0.1
Description: Get list of firewall rules for a specified server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/firewall_rule
Request Type: GET
Parameters:
serveruuid
: UUID of the server
Description: Get details of a specific firewall rule for a specified rules
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/firewall_rule/[INDEX]
Request Type: GET
Parameters:
serveruuid
: UUID of the serverindex
: Index of the rule in the list of firewall rules for the server (first entry is index1
)
Description: Create a firewall rule for a specified server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/firewall_rule
Request Type: POST
Parameters:
serveruuid
: UUID of the server
POST Data: See the UpCloud API documentation
Description: Create multiple firewall rules for a specified server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/firewall_rule
Request Type: PUT
Parameters:
serveruuid
: UUID of the server
PUT Data: See the UpCloud API documentation
Description: Remove a specific firewall rule from a specified rules
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/firewall_rule/[INDEX]
Request Type: DELETE
Parameters:
serveruuid
: UUID of the serverindex
: Index of the rule in the list of firewall rules for the server (first entry is index1
)
Description: Get list of tags
UpCloud API Endpoint: https://api.upcloud.com/1.3/tag
Request Type: GET
Parameters: None
Description: Create a tag
UpCloud API Endpoint: https://api.upcloud.com/1.3/tag
Request Type: POST
Parameters: None
POST Data: See the UpCloud API documentation
Description: Modify a tag
UpCloud API Endpoint: https://api.upcloud.com/1.3/tag/[TAG]
Request Type: PUT
Parameters:
tag
: Name of tag to modify
PUT Data: See the UpCloud API documentation
Description: Delete a tag
UpCloud API Endpoint: https://api.upcloud.com/1.3/tag/[TAG]
Request Type: DELETE
Parameters:
tag
: Name of tag to modify
Description: Assign one or more tags to a server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/tag/[TAGS]
Request Type: POST
Parameters:
serveruuid
: UUID of servertags
: Comma-separated list of tags to assign to server
POST Data: See the UpCloud API documentation
Description: Remove one or more tags from a server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/untag/[TAGS]
Request Type: POST
Parameters:
serveruuid
: UUID of servertags
: Comma-separated list of tags to assign to server
POST Data: See the UpCloud API documentation
Description: Get list of available hosts
UpCloud API Endpoint: https://api.upcloud.com/1.3/host
Request Type: GET
Parameters: None
Description: Get details of a specified host
UpCloud API Endpoint: https://api.upcloud.com/1.3/host/[ID]
Request Type: GET
Parameters:
hostid
: ID of host
Description: Modify description of a specified host
UpCloud API Endpoint: https://api.upcloud.com/1.3/host/[ID]
Request Type: PATCH
Parameters:
hostid
: ID of host
PATCH Data: See the UpCloud API documentation
Description: Get list of networks
UpCloud API Endpoint: https://api.upcloud.com/1.3/network
Request Type: GET
Parameters: None
Description: Get list of networks in a specific zone
UpCloud API Endpoint: https://api.upcloud.com/1.3/network/?zone=[ZONE]
Request Type: GET
Parameters:
zone
: Zone name
Description: Get list of networks a specific server is connected to
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/networking]
Request Type: GET
Parameters:
serveruuid
: UUID of server
Description: Get details of a specific network
UpCloud API Endpoint: https://api.upcloud.com/1.3/network/[UUID]
Request Type: GET
Parameters:
networkuuid
: UUID of network
Description: Modify details of a specific network
UpCloud API Endpoint: https://api.upcloud.com/1.3/network/[UUID]
Request Type: POST
Parameters:
networkuuid
: UUID of network
POST Data: See the UpCloud API documentation
Description: Creates new SDN private network
UpCloud API Endpoint: https://api.upcloud.com/1.3/network
Request Type: POST
Parameters: None
POST Data: See the UpCloud API documentation
Description: Delete a specific network
UpCloud API Endpoint: https://api.upcloud.com/1.3/network/[UUID]
Request Type: DELETE
Parameters:
networkuuid
: UUID of network
Description: Creates new network interface on a specified server and connect it to an SDN private network
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/networking/interface
Request Type: POST
Parameters:
serveruuid
: UUID of server
POST Data: See the UpCloud API documentation
Description: Modifies details of a network interface on a specified server
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/networking/interface/[INDEX]
Request Type: PUT
Parameters:
serveruuid
: UUID of serverinterface
: Index of the network interface from the server
PUT Data: See the UpCloud API documentation
Description: Deletes a network interface on a specified server and disconencts from an SDN private network
UpCloud API Endpoint: https://api.upcloud.com/1.3/server/[UUID]/networking/interface/[INDEX]
Request Type: DELETE
Parameters:
serveruuid
: UUID of serverinterface
: Index of the network interface from the server
Description: Get list of routers
UpCloud API Endpoint: https://api.upcloud.com/1.3/route
Request Type: GET
Parameters: None
Description: Get details of a specified router
UpCloud API Endpoint: https://api.upcloud.com/1.3/route/[UUID]
Request Type: GET
Parameters:
routeruuid
: UUID of router
Description: Create a router
UpCloud API Endpoint: https://api.upcloud.com/1.3/route
Request Type: POST
Parameters: None
POST Data: See the UpCloud API documentation
Description: Modify a router
UpCloud API Endpoint: https://api.upcloud.com/1.3/route/[UUID]
Request Type: PATCH
Parameters:
routeruuid
: UUID of router
PATCH Data: See the UpCloud API documentation
Description: Delete a router
UpCloud API Endpoint: https://api.upcloud.com/1.3/route/[UUID]
Request Type: DELETE
Parameters:
routeruuid
: UUID of router
Description: Get list of object storage resources
UpCloud API Endpoint: https://api.upcloud.com/1.3/object-storage
Request Type: GET
Parameters: None
Description: Get details of an object storage resources
UpCloud API Endpoint: https://api.upcloud.com/1.3/object-storage/[UUID]
Request Type: GET
Parameters:
objectuuid
: UUID of object storage resources
Description: Create a new object storage resources
UpCloud API Endpoint: https://api.upcloud.com/1.3/object-storage
Request Type: POST
Parameters: None
POST Data: See the UpCloud API documentation
Description: Modify an object storage resources
UpCloud API Endpoint: https://api.upcloud.com/1.3/object-storage/[UUID]
Request Type: PATCH
Parameters:
objectuuid
: UUID of object storage resources
PATCH Data: See the UpCloud API documentation
Description: Delete an object storage resources
UpCloud API Endpoint: https://api.upcloud.com/1.3/object-storage/[UUID]
Request Type: DELETE
Parameters:
objectuuid
: UUID of object storage resources
Description: Get network usage of an object storage resource for a time range
UpCloud API Endpoint: https://api.upcloud.com/1.3/object-storage/[UUID]/stats/network/?from=[FROM]&to=[TO]
Request Type: GET
Parameters:
objectuuid
: UUID of object storage resourcefrom
: Timestamp for start of time period in RFC 3339 format (YYYY-MM-DDTHH:MM:SSZ)to
: Timestamp for end of time period in RFC 3339 format (YYYY-MM-DDTHH:MM:SSZ)
upcloud-api
depends on the following npm
/Node packages:
request
- Simplified HTTP client for connecting to the UpCloud endpoints
This version is upcloud-api
Copyright 2021, @likeablegeek. Distributed by FlightSim Ninja.
You may not use this work/module/file except in compliance with the License. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.