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.

Table of content

• Installation
• Usage
• Documentation
• Issues
• License

Requirements

Using this library requires the PHP version 5.5 and later.

Installation

Composer

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

{
  "require": {
    "upcloudltd/upcloud-php-api": "v1.0.3"
  }
}

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
UPCLOUD_API_TEST_USER=user UPCLOUD_API_TEST_PASSWORD=pass ./vendor/bin/phpunit

Note: You need to supply an UpCloud account's details to run the tests. The tests will create/modify/delete servers under this account in the actual UpCloud environment, so please use a test account.

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-000030040200');
$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.2

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