PHP client for UpCloud's API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.swagger-codegen
docs
lib
test
.DS_Store
.gitignore
.php_cs
.swagger-codegen-ignore
.travis.yml
LICENSE
README.md
composer.json
composer.lock
phpconfig.ini
phpunit.xml.dist

README.md

UpCloud PHP API client library

Build Status Latest Stable Version License Total Downloads

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

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.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-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

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.