upcloud_api 1.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6837056b4cff07402d608702a95d56d6be14ec38
-  data.tar.gz: 82526825eb93b43aef2160e3fc1ebcb5a689114d
+  metadata.gz: 9b9499c81732dab73f760bcfc382a7c288d82960
+  data.tar.gz: 61ec8087b5b00f870495fdf4c9859e962c8675f4
 SHA512:
-  metadata.gz: 3ff71fa95959d11049d3d55398fd17f8b84baf43600c6bf38990ae9ccf58ba5521b3b82d405a1691085257854caa0d90755421d2ec0a4d5734b72a06eb879819
-  data.tar.gz: 7a158330aff7be804d5a9f386bf6b0baff416ef6b176eb4e3521d0de512384b9381051fb77338f0f35c083f1259adb4a052921a5c734e138157dfa0fd597d970
+  metadata.gz: 52496d8d4289e67cf15da5703500e497201d312553c78eaf58e548d1958796075177405ae5b5acc75dbfc1a594bc6b6fc7913cc8d789c7cce7cbdbb47b4c7e8e
+  data.tar.gz: edab2b929517934e42e082142ae19b5c186116b4a3cc248cf31df506974b415641dd4e46efbe07d175fa100c120b63f642bcd799ac06352ac35de4a0e66d3660

data/lib/upcloud_api.rb

@@ -19,7 +19,7 @@ class UpcloudApi
   #
   # Calls GET /1.2/server
   #
-  # Returns true in success, false if not
+  # Returns true in success, false if not.
   def login
     response = get "server"
     response.code == 200
@@ -27,7 +27,13 @@ class UpcloudApi
 
   # Returns available server configurations.
   #
-  # Calls GET /1.2/server_size
+  # Calls GET /1.2/server_size.
+  #
+  # Returns array of server size hashes:
+  #   {
+  #     "core_number": "1",
+  #     "memory_amount": "512"
+  #   }
   def server_configurations
     response = get "server_size"
     response["server_sizes"]["server_size"]
@@ -36,17 +42,19 @@ class UpcloudApi
   # Returns available credits.
   #
   # Calls GET /1.2/acccount
+  #
+  # Returns available credits in the account as a string.
   def account_information
     response = get "account"
     data = JSON.parse response.body
     data["account"]["credits"]
   end
 
-  # Lists servers associated with the account
+  # Lists servers associated with the account.
   #
-  # Calls GET /1.2/server
+  # Calls GET /1.2/server.
   #
-  # Returns array of servers with values
+  # Returns array of servers with following values or empty array if no servers found.
   # - zone
   # - core_number
   # - title
@@ -62,54 +70,121 @@ class UpcloudApi
 
   # Shows details of a server.
   #
-  # Calls GET /1.2/server/#{uuid}
+  # Calls GET /1.2/server/_uuid_.
   #
   # @param uuid from UpcloudApi#servers
+  #
+  # Returns hash of server details or nil:
+  #   {
+  #    "boot_order"         => "cdrom,disk",
+  #    "core_number"        => "3",
+  #    "firewall"           => "off",
+  #    "hostname"           => "dummy",
+  #    "ip_addresses"       => {
+  #      "ip_address" => [
+  #        {
+  #          "access" => "private",
+  #          "address"            => "192.168.0.1",
+  #         "family"             => "IPv4"
+  #        },
+  #        {
+  #          "access"            => "public",
+  #          "address"            => "::1",
+  #          "family"             => "IPv6"
+  #        },
+  #        {
+  #          "access"            => "public",
+  #          "address"            => "198.51.100.1",
+  #          "family"             => "IPv4"
+  #        }
+  #      ]
+  #    },
+  #    "license"            => 0,
+  #    "memory_amount"      => "3072",
+  #    "nic_model"          => "virtio",
+  #    "plan"               => "custom",
+  #    "state"              => "stopped",
+  #    "storage_devices"    => {
+  #      "storage_device" => [
+  #        {
+  #          "address" => "virtio:1",
+  #          "storage"            => "storage_uuid",
+  #          "storage_size"       => 10,
+  #          "storage_title"      => "Disk name",
+  #          "type"               => "disk"
+  #        }
+  #      ]
+  #    },
+  #    "tags"               => {"tag" => []},
+  #    "timezone"           => "UTC",
+  #    "title"              => "Server name",
+  #    "uuid"               => "uuid",
+  #    "video_model"        => "cirrus",
+  #    "vnc"                => "off",
+  #    "vnc_password"       => "1234",
+  #    "zone"               => "de-fra1"
+  #   }
   def server_details(uuid)
     response = get "server/#{uuid}"
     data = JSON.parse response.body
-    data
-  end
 
-  # Lists templates available from Upcloud
-  #
-  # Calls GET /1.2/storage/template
-  def templates
-    response = get "storage/template"
-    data = JSON.parse response.body
-    data
+    return nil if data["server"].nil?
+
+    data["server"]
   end
 
   # Creates new server from template.
   #
-  # Calls POST /1.2/server
+  # Calls POST /1.2/server.
   #
   # Storage devices should be array of hashes containing following data:
   #
   #   {
-  #   "action" => "clone" # Can be "create", "clone" or "attach"
-  #   "storage" => template_uuid, # Should be passed only for "clone" or "attach"
-  #   "title" => disk_name # Name of the storage,
-  #   "tier" => "maxiops" # No sense using HDD any more
+  #     "action"  => "clone"          # Can be "create", "clone" or "attach"
+  #     "storage" => template_uuid,   # Should be passed only for "clone" or "attach"
+  #     "title"   => disk_name,       # Name of the storage,
+  #     "tier"    => "maxiops",       # No sense using HDD any more
+  #   }
+  #
+  # @param plan [String] Preconfigured plan for the server. If nil, a custom plan will be created from input data, otherwise this overrides custom configuration.
+  #   Predefined plans can be fetched with {#plans}.
+  #
+  # login_user should be following hash or nil:
+  #   {
+  #     "username": "upclouduser",
+  #     "ssh_keys": {
+  #       "ssh_key": [
+  #          "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x user@some.host",
+  #          "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== someuser@some.other.host"
+  #        ]
+  #     }
   #   }
   #
   # ip_addresses should be an array containing :public, :private and/or :ipv6. It defaults to
   # :all, which means the server will get public IPv4, private IPv4 and public IPv6 addresses.
   #
-  # Returns HTTParty response
+  # @param other [Hash] Other optional arguments create_server API call takes. See Upcloud’s documentation for possible values.
+  #
+  # Returns HTTParty response object.
   def create_server(zone: "fi-hel1", title:, hostname:, core_number: 1,
-                    memory_amount: 1024, storage_devices:, ip_addresses: :all)
+                    memory_amount: 1024, storage_devices:, ip_addresses: :all,
+                    plan: nil, login_user: nil, other: nil)
     data = {
       "server" => {
         "zone" => zone,
         "title" => title,
         "hostname" => hostname,
-        "core_number" => core_number,
-        "memory_amount" => memory_amount,
         "storage_devices" => { "storage_device" => storage_devices }
       }
     }
 
+    if plan.nil?
+        data["server"]["core_number"] = core_number
+        data["server"]["memory_amount"] = memory_amount
+    else
+        data["server"]["plan"] = plan
+    end
+
     if ip_addresses != :all
       ips = []
       ips << { "access" => "public", "family" => "IPv4" } if ip_addresses.include? :public
@@ -120,6 +195,14 @@ class UpcloudApi
       data["server"]["ip_addresses"]["ip_address"] = ips
     end
 
+    unless login_user.nil?
+        data["login_user"] = login_user
+    end
+
+    unless other.nil?
+        data.merge! other
+    end
+
     json = JSON.generate data
     response = post "server", json
     response
@@ -129,10 +212,12 @@ class UpcloudApi
   #
   # In order to modify a server, the server must be stopped first.
   #
-  # Calls PUT /1.2/server/#{uuid}
+  # Calls PUT /1.2/server/_uuid_.
   #
   # @param server_uuid [String] UUID of the server that will be modified.
   # @param params [Hash] Hash of params that will be passed to be changed.
+  #
+  # Returns HTTParty response object.
   def modify_server(server_uuid, params)
     data = { "server" => params }
     json = JSON.generate data
@@ -145,7 +230,9 @@ class UpcloudApi
   #
   # In order to delete a server, the server must be stopped first.
   #
-  # Calls DELETE /1.2/server/#{uuid}
+  # Calls DELETE /1.2/server/_uuid_.
+  #
+  # Returns HTTParty response object.
   def delete_server(server_uuid)
     response = delete "server/#{server_uuid}"
 
@@ -154,18 +241,20 @@ class UpcloudApi
 
   # Starts server that is shut down.
   #
-  # Calls POST /1.2/server/#{uuid}/start
+  # Calls POST /1.2/server/_uuid_/start.
   #
-  # @param server_uuid UUID of the server
+  # @param server_uuid UUID of the server.
+  #
+  # Returns HTTParty response object.
   def start_server(server_uuid)
     response = post "server/#{server_uuid}/start"
 
     response
   end
 
-  # Shuts down a server that is currently running
+  # Shuts down a server that is currently running.
   #
-  # Calls POST /1.2/server/#{uuid}/stop
+  # Calls POST /1.2/server/_uuid_/stop.
   #
   # Hard shutdown means practically same as taking the power cable
   # off from the computer. Soft shutdown sends ACPI signal to the server,
@@ -183,6 +272,8 @@ class UpcloudApi
   #
   # Raises Timeout::Error in case server does not shut down in 300
   # seconds in non-asynchronous mode.
+  #
+  # Returns HTTParty response object if server was removed successfully or request is asynchronous and nil otherwise
   def stop_server(server_uuid, type: :soft, timeout: nil, asynchronous: false)
     data = {
       "stop_server" => {
@@ -200,15 +291,17 @@ class UpcloudApi
     Timeout.timeout 300 do
       loop do
         details = server_details server_uuid
-        return response if details["server"].nil?
-        return response if details["server"]["state"] == "stopped"
+        return response if details.nil?
+        return response if details["state"] == "stopped"
       end
     end
+
+    nil
   end
 
-  # Restarts a server that is currently running
+  # Restarts a server that is currently running.
   #
-  # Calls POST /1.2/server/#{uuid}/restart
+  # Calls POST /1.2/server/_uuid_/restart.
   #
   # Hard shutdown means practically same as taking the power cable
   # off from the computer. Soft shutdown sends ACPI signal to the server,
@@ -224,8 +317,9 @@ class UpcloudApi
   # @param timeout_action What will happen when timeout happens.
   # :destroy hard stops the server and :ignore stops the operation
   # if timeout happens. Default is :ignore.
-  def restart_server(server_uuid, type: :soft, timeout: nil,
-                     timeout_action: :ignore)
+  #
+  # Returns HTTParty response object.
+  def restart_server(server_uuid, type: :soft, timeout: nil, timeout_action: :ignore)
     data = {
       "restart_server" => {
         "stop_type" => type.to_s,
@@ -243,7 +337,7 @@ class UpcloudApi
 
   # Lists all storages or storages matching to given type.
   #
-  # Calls GET /1.2/storage or /1.2/storage/#{type}
+  # Calls GET /1.2/storage or /1.2/storage/_type_.
   #
   # Available types:
   # - public
@@ -254,27 +348,46 @@ class UpcloudApi
   # - template
   # - favorite
   #
-  # @param type Type of the storages to be returned on nil
+  # @param type Type of the storages to be returned on nil.
+  #
+  # Returns array of storages, inside "storage" key in the API or empty array if none found.
   def storages(type: nil)
     response = get(type && "storage/#{type}" || "storage")
     data = JSON.parse response.body
-    data
+    data["storages"]["storage"]
   end
 
   # Shows detailed information of single storage.
   #
-  # Calls GET /1.2/storage/#{uuid}
+  # Calls GET /1.2/storage/_uuid_.
+  #
+  # @param storage_uuid UUID of the storage.
   #
-  # @param storage_uuid UUID of the storage
+  # Returns hash of following storage details or nil:
+  #   {
+  #     "access"  => "public",
+  #     "license" => 0,
+  #     "servers" => {
+  #         "server"=> []
+  #       },
+  #     "size"    => 1,
+  #     "state"   => "online",
+  #     "title"   => "Windows Server 2003 R2 Standard (CD 1)",
+  #     "type"    => "cdrom",
+  #     "uuid"    => "01000000-0000-4000-8000-000010010101"
+  #   }
   def storage_details(storage_uuid)
     response = get "storage/#{storage_uuid}"
     data = JSON.parse response.body
-    data
+
+    return nil if data["storage"].nil?
+
+    data["storage"]
   end
 
   # Creates new storage.
   #
-  # Calls POST /1.2/storage
+  # Calls POST /1.2/storage.
   #
   # backup_rule should be hash with following attributes:
   # - interval # allowed values: daily / mon / tue / wed / thu / fri / sat / sun
@@ -289,6 +402,8 @@ class UpcloudApi
   # with the server
   # @param backup_rule Hash of backup information. If not given, no
   # backups will be automatically created.
+  #
+  # Returns HTTParty response object.
   def create_storage(size:, tier: "maxiops", title:, zone: "fi-hel1",
                      backup_rule: nil)
     data = {
@@ -309,7 +424,7 @@ class UpcloudApi
 
   # Modifies existing storage.
   #
-  # Calls PUT /1.2/storage/#{uuid}
+  # Calls PUT /1.2/storage/_uuid_.
   #
   # backup_rule should be hash with following attributes:
   # - interval # allowed values: daily / mon / tue / wed / thu / fri / sat / sun
@@ -321,6 +436,8 @@ class UpcloudApi
   # @param title Name of the disk
   # @param backup_rule Hash of backup information. If not given, no
   # backups will be automatically created.
+  #
+  # Returns HTTParty response object.
   def modify_storage(storage_uuid, size:, title:, backup_rule: nil)
     data = {
       "storage" => {
@@ -341,7 +458,7 @@ class UpcloudApi
   #
   # This operation is asynchronous.
   #
-  # Calls POST /1.2/storage/#{uuid}/clone
+  # Calls POST /1.2/storage/_uuid_/clone.
   #
   # @param storage_uuid UUID of the storage that will be modified
   # @param tier Type of the disk. maxiops is SSD powered disk, other
@@ -349,6 +466,8 @@ class UpcloudApi
   # @param title Name of the disk
   # @param zone Where the disk will reside. Needs to be within same zone
   # with the server
+  #
+  # Returns HTTParty response object.
   def clone_storage(storage_uuid, zone: "fi-hel1", title:, tier: "maxiops")
     data = {
       "storage" => {
@@ -369,10 +488,12 @@ class UpcloudApi
   #
   # This operation is asynchronous.
   #
-  # Calls POST /1.2/storage/#{uuid}/templatize
+  # Calls POST /1.2/storage/_uuid_/templatize.
   #
   # @param storage_uuid UUID of the storage that will be templatized
   # @param title Name of the template storage
+  #
+  # Returns HTTParty response object.
   def templatize_storage(storage_uuid, title:)
     data = {
       "storage" => {
@@ -390,7 +511,7 @@ class UpcloudApi
   # Attaches a storage to a server. Server must be stopped before the
   # storage can be attached.
   #
-  # Calls POST /1.2/server/#{server_uuid}/storage/attach
+  # Calls POST /1.2/server/_server_uuid_/storage/attach.
   #
   # Valid values for address are: ide[01]:[01] / scsi:0:[0-7] / virtio:[0-7]
   #
@@ -399,6 +520,8 @@ class UpcloudApi
   # @param type Type of the disk. Valid values are "disk" and "cdrom".
   # @param address Address where the disk will be attached to. Defaults
   # to next available address.
+  #
+  # Returns HTTParty response object.
   def attach_storage(server_uuid, storage_uuid:, type: "disk", address: nil)
     data = {
       "storage_device" => {
@@ -418,10 +541,12 @@ class UpcloudApi
   # Detaches storage from a server. Server must be stopped before the
   # storage can be detached.
   #
-  # Calls POST /1.2/server/#{server_uuid}/storage/detach
+  # Calls POST /1.2/server/_server_uuid_/storage/detach.
   #
   # @param server_uuid UUID of the server from which to detach the storage.
   # @param address Address where the storage that will be detached resides.
+  #
+  # Returns HTTParty response object.
   def detach_storage(server_uuid, address:)
     data = {
       "storage_device" => {
@@ -440,10 +565,12 @@ class UpcloudApi
   #
   # This operation is asynchronous.
   #
-  # Calls /1.2/storage/#{uuid}/backup
+  # Calls /1.2/storage/_uuid_/backup
   #
   # @param storage_uuid UUID of the storage to be backed-up
   # @param title Name of the backup
+  #
+  # Returns HTTParty response object.
   def create_backup(storage_uuid, title:)
     data = {
       "storage" => {
@@ -462,31 +589,37 @@ class UpcloudApi
   #
   # If the storage is attached to server, the server must first be stopped.
   #
-  # Calls /1.2/storage/#{backup_uuid}/restore.
+  # Calls /1.2/storage/_backup_uuid_/restore.
   #
   # @param backup_uuid UUID of the backup
+  #
+  # Returns HTTParty response object.
   def restore_backup(backup_uuid)
     response = post "storage/#{backup_uuid}/restore"
 
     response
   end
 
-  # Adds storage to favorites
+  # Adds storage to favorites.
   #
-  # Calls POST /1.2/storage/#{storage_uuid}/favorite.
+  # Calls POST /1.2/storage/_storage_uuid_/favorite.
   #
   # @param storage_uuid UUID of the storage to be included in favorites
+  #
+  # Returns HTTParty response object.
   def favorite_storage(storage_uuid)
     response = post "storage/#{storage_uuid}/favorite"
 
     response
   end
 
-  # Removes storage to favorites
+  # Removes storage to favorites.
   #
-  # Calls POST /1.2/storage/#{storage_uuid}/favorite.
+  # Calls POST /1.2/storage/_storage_uuid_/favorite.
   #
   # @param storage_uuid UUID of the storage to be removed from favorites
+  #
+  # Returns HTTParty response object.
   def defavorite_storage(storage_uuid)
     response = delete "storage/#{storage_uuid}/favorite"
 
@@ -500,12 +633,34 @@ class UpcloudApi
   # Backups will not be deleted.
   #
   # @param storage_uuid UUID of the storage that will be deleted.
+  #
+  # Returns HTTParty response object.
   def delete_storage(storage_uuid)
     response = delete "storage/#{storage_uuid}"
 
     response
   end
 
+  # Lists available predefined plans that can be used to create a server.
+  #
+  # Returns Array of plan hashes:
+  #   [
+  #    {
+  #      "core_number" : 1,
+  #      "memory_amount" : 1024,
+  #      "name" : "1xCPU-1GB",
+  #      "public_traffic_out" : 2048,
+  #      "storage_size" : 30,
+  #      "storage_tier" : "maxiops"
+  #    }
+  #   ]
+  def plans
+    response = get "plan"
+
+    data = JSON.parse response.body
+    data["plans"]["plan"]
+  end
+
   private
 
   def get(action)

data/lib/upcloud_api/version.rb

@@ -1,3 +1,3 @@
 class UpcloudApi
-  VERSION = "1.5.0".freeze
+  VERSION = "2.0.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: upcloud_api
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Samu Voutilainen
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-22 00:00:00.000000000 Z
+date: 2017-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -54,9 +54,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Implementation of Upcloud API for VPS management
 test_files: []
-has_rdoc: