upcloudltd/upcloud-php-api

UpCloud PHP API

v2.1.0 2021-06-09 14:49 UTC

README

UpCloud php api test 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.

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

Requirements

Using this library requires the PHP version 7.2 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

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.