UpCloud PHP API client library

This PHP API client library provides integration with the UpCloud API allowing operations used to manage resources on UpCloud. The client is a web service interface that uses HTTPS to connect to the API. The API follows the principles of a RESTful web service 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.

NOTE: Please test all of your use cases thoroughly before actual production use. Using a separate UpCloud account for testing / developing the client is recommended.

Table of content

• Installation
• Usage
• Documentation
• Issues
• License

Requirements

Using this library requires the PHP version 8.0 and later.

Installation

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "require": {
    "upcloudltd/upcloud-php-api": "v2.0.0"
  }
}

Then run composer install

The upcloudltd/upcloud-php-api can be found from packagist.org, https://packagist.org/packages/upcloudltd/upcloud-php-api

Manual installation

Download the files and include autoload.php:

    require_once('/path/to//vendor/autoload.php');

Tests

To run the unit tests:

composer install

./vendor/bin/phpunit

Usage

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

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Upcloud\ApiClient\Upcloud\AccountApi();
$config = $api_instance->getConfig();
$config->setUsername('YOUR UPCLOUD USERNAME');
$config->setPassword('YOUR UPCLOUD PASSWORD');

try {
    $result = $api_instance->getAccount();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AccountApi->getAccount: ', $e->getMessage(), PHP_EOL;
}

?>

To create a server:

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$api_instance = new Upcloud\ApiClient\Upcloud\AccountApi();
$config = $api_instance->getConfig();
$config->setUsername('YOUR UPCLOUD USERNAME');
$config->setPassword('YOUR UPCLOUD PASSWORD');

try {
        $result = $api_instance->getAccount();
            print_r($result);
} catch (Exception $e) {
        echo 'Exception when calling AccountApi->getAccount: ', $e->getMessage(), PHP_EOL;
}

$server = new Upcloud\ApiClient\Model\Server();
$server->setTitle('php-test-machine');
$server->setZone('fi-hel1');
$server->setHostname('phptest');
$server->setPlan('1xCPU-1GB');

$storage = new Upcloud\ApiClient\Model\StorageDevice();
$storage->setStorage('01000000-0000-4000-8000-000030060200');
$storage->setSize(50.0);
$storage->setAction('clone');
$storage->setTitle('php-test-storage');

$storage_devices = new Upcloud\ApiClient\Model\ServerStorageDevices();
$storage_devices->setStorageDevice([$storage]);

$server->setStorageDevices($storage_devices);

$server_request = new Upcloud\ApiClient\Model\CreateServerRequest();
$server_request->setServer($server);
$api_instance = new Upcloud\ApiClient\Upcloud\ServerApi();
try {
        $result = $api_instance->createServer($server_request);
            print_r($result);
} catch (Exception $e) {
        echo 'Exception when calling ServerApi->createServer: ', $e->getMessage(), PHP_EOL;
}

?>

Documentation

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

Class	Method	HTTP request	Description
AccountApi	getAccount	GET /account	Account information
FirewallApi	createFirewallRule	POST /server/{serverId}/firewall_rule	Create firewall rule
FirewallApi	deleteFirewallRule	DELETE /server/{serverId}/firewall_rule/{firewallRuleNumber}	Remove firewall rule
FirewallApi	getFirewallRule	GET /server/{serverId}/firewall_rule/{firewallRuleNumber}	Get firewall rule details
FirewallApi	serverServerIdFirewallRuleGet	GET /server/{serverId}/firewall_rule	List firewall rules
IPAddressApi	addIp	POST /ip_address	Assign IP address
IPAddressApi	deleteIp	DELETE /ip_address/{ip}	Release IP address
IPAddressApi	getDetails	GET /ip_address/{ip}	Get IP address details
IPAddressApi	listIps	GET /ip_address	List IP addresses
IPAddressApi	modifyIp	PUT /ip_address/{ip}	Modify IP address
NetworkApi	getListNetworks	GET /network	List all Networks
NetworkApi	getNetworkDetails	GET /network/{uuid}	Get Network details
NetworkApi	createNetwork	POST /network	Create a new SDN private network
NetworkApi	modifyNetwork	PUT /network/{id}	Modify a specific SDN private network
NetworkApi	deleteNetwork	DELETE /network/{id}	Delete a SDN private network
NetworkApi	getListServerNetworks	GET server/{server_id}/networking	List all Networks
NetworkApi	createNetworkInterface	POST server/{server}/networking/interface	Create a new network interface
NetworkApi	modifyNetworkInterface	PUT /network/{id}	Modify network interface
NetworkApi	deleteNetworkInterface	DELETE /network/{id}	Delete network interface
NetworkApi	getListRouters	GET /router	List of all available routers
NetworkApi	getRouterDetails	GET /router/{uuid}	Get router details
NetworkApi	createRouter	POST /router	Create a new router
NetworkApi	modifyRouter	PUT /router/{id}	Modify an existing router
NetworkApi	deleteRouter	DELETE /router/{id}	Delete an existing router
ObjectStorageApi	getListObjectStorage	GET /object-storage	List all Object Storage
ObjectStorageApi	getObjectStorageDetails	GET /object-storage/{uuid}	Get Object Storage details
ObjectStorageApi	createObjectStorage	POST /object-storage	Create a new Object Storage
ObjectStorageApi	modifyObjectStorage	PATCH /object-storage/{id}	Modify Object Storage
ObjectStorageApi	deleteObjectStorage	DELETE /object-storage/{id}	Release Object Storage
HostsApi	getListHosts	GET /host	List of available hosts
HostsApi	getHostDetails	GET /host/{id}	Get detailed information about a specific host
HostsApi	modifyHost	PATCH /host/{id}	Modify specific host
PlanApi	listPlans	GET /plan	List available plans
PricesApi	listPrices	GET /price	List prices
ServerApi	assignTag	POST /server/{serverId}/tag/{tagList}	Assign tag to a server
ServerApi	attachStorage	POST /server/{serverId}/storage/attach	Attach storage
ServerApi	createFirewallRule	POST /server/{serverId}/firewall_rule	Create firewall rule
ServerApi	createServer	POST /server	Create server
ServerApi	deleteFirewallRule	DELETE /server/{serverId}/firewall_rule/{firewallRuleNumber}	Remove firewall rule
ServerApi	deleteServer	DELETE /server/{serverId}	Delete server
ServerApi	detachStorage	POST /server/{serverId}/storage/detach	Detach storage
ServerApi	ejectCdrom	POST /server/{serverId}/cdrom/eject	Eject CD-ROM
ServerApi	getFirewallRule	GET /server/{serverId}/firewall_rule/{firewallRuleNumber}	Get firewall rule details
ServerApi	listServerConfigurations	GET /server_size	List server configurations
ServerApi	listServers	GET /server	List of servers
ServerApi	loadCdrom	POST /server/{serverId}/storage/cdrom/load	Load CD-ROM
ServerApi	modifyServer	PUT /server/{serverId}	Modify server
ServerApi	restartServer	POST /server/{serverId}/restart	Restart server
ServerApi	serverDetails	GET /server/{serverId}	Get server details
ServerApi	serverServerIdFirewallRuleGet	GET /server/{serverId}/firewall_rule	List firewall rules
ServerApi	startServer	POST /server/{serverId}/start	Start server
ServerApi	stopServer	POST /server/{serverId}/stop	Stop server
ServerApi	untag	POST /server/{serverId}/untag/{tagName}	Remove tag from server
StorageApi	attachStorage	POST /server/{serverId}/storage/attach	Attach storage
StorageApi	backupStorage	POST /storage/{storageId}/backup	Create backup
StorageApi	cancelOperation	POST /storage/{storageId}/cancel	Cancel storage operation
StorageApi	cloneStorage	POST /storage/{storageId}/clone	Clone storage
StorageApi	createStorage	POST /storage	Create storage
StorageApi	deleteStorage	DELETE /storage/{storageId}	Delete storage
StorageApi	detachStorage	POST /server/{serverId}/storage/detach	Detach storage
StorageApi	ejectCdrom	POST /server/{serverId}/cdrom/eject	Eject CD-ROM
StorageApi	favoriteStorage	POST /storage/{storageId}/favorite	Add storage to favorites
StorageApi	getStorageDetails	GET /storage/{storageId}	Get storage details
StorageApi	listStorageTypes	GET /storage/{type}/	List of storages by type
StorageApi	listStorages	GET /storage	List of storages
StorageApi	loadCdrom	POST /server/{serverId}/storage/cdrom/load	Load CD-ROM
StorageApi	modifyStorage	PUT /storage/{storageId}	Modify storage
StorageApi	restoreStorage	POST /storage/{storageId}/restore	Restore backup
StorageApi	templatizeStorage	POST /storage/{storageId}/templatize	Templatize storage
StorageApi	unfavoriteStorage	DELETE /storage/{storageId}/favorite	Remove storage from favorites
TagApi	assignTag	POST /server/{serverId}/tag/{tagList}	Assign tag to a server
TagApi	createTag	POST /tag	Create a new tag
TagApi	deleteTag	DELETE /tag/{tagName}	Delete tag
TagApi	listTags	GET /tag	List existing tags
TagApi	modifyTag	PUT /tag/{tagName}	Modify existing tag
TagApi	untag	POST /server/{serverId}/untag/{tagName}	Remove tag from server
TimezoneApi	listTimezones	GET /timezone	List timezones
ZoneApi	listZones	GET /zone	List available zones

Documentation of the models

• Account
• AccountResourceLimits
• AccountResponse
• AddIpRequest
• AssignIpResponse
• AttachNetwork
• AttachStorageDeviceRequest
• AvailablePlanListResponse
• AvailablePlanListResponsePlans
• BackupRule
• CloneStorageRequest
• ConfigurationListResponse
• ConfigurationListResponseServerSizes
• CreateBackupStorageRequest
• CreateNewTagResponse
• CreateServerRequest
• CreateServerResponse
• CreateStorageRequest
• CreateStorageResponse
• Error
• ErrorCode
• ErrorError
• ErrorStatus
• FirewallRule
• FirewallRuleCreateResponse
• FirewallRuleListResponse
• FirewallRuleListResponseFirewallRules
• FirewallRuleRequest
• Host
• IpAddress
• IpAddressListResponse
• IpAddresses
• IpNetwork
• ModifyIpRequest
• ModifyServerRequest
• ModifyStorageRequest
• ModifyTagRequest
• Network
• NetworkInterface
• ObjectStorage
• Plan
• Price
• PriceListResponse
• PriceListResponsePrices
• PriceZone
• RestartServer
• Router
• Server
• ServerListResponse
• ServerListResponseServers
• ServerLoginUser
• ServerSize
• ServerState
• ServerStorageDevices
• ServerTags
• Stat
• StopServer
• StopServerRequest
• Storage
• StorageAccessType
• StorageBackups
• StorageDevice
• StorageDeviceDetachRequest
• StorageDeviceLoadRequest
• Servers
• StorageState
• StorageTier
• StorageType
• SuccessStoragesResponse
• SuccessStoragesResponseStorages
• Tag
• TagCreateRequest
• TagListResponse
• TagListResponseTags
• TagServers
• TemplitizeStorageRequest
• TimezoneListResponse
• TimezoneListResponseTimezones
• Zone
• ZoneListResponse
• ZoneListResponseZones

Documentation for authorization

It's recommended to store the username and password in a separate configuration file 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.