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

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.