ARCHITECTURE OVERVIEW

API overview

The UpCloud API consists of operations used to control resources on UpCloud. The API is a web service interface. HTTPS is used 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/. All API operations require authentication.

API versioning

The API uses versioning to allow backwards incompatible modifications in the service without affecting clients using older versions of the API.

The versioning uses an X.Y.Z scheme. The X.Y part is shown in the URL, e.g. https://api.upcloud.com/1.2/.

Backwards compatible changes in the API does not require changes to clients using the API. Such changes include but are not limited to adding or modifying error codes and messages or adding new features. When backwards compatible changes are made to the API, the Z version is incremented.

Small and large backwards incompatible changes increment the Y or X version respectively. Upgrading to a backwards incompatible API version require changing the URLs that are used to access the service.

Changes to the API are noted in the Version history.

If an invalid or inexistent API version is requested, the error code API_VERSION_INVALID is returned. If an obsolete API version is requested, the error code API_VERSION_OBSOLETE is returned.

Authentication

The UpCloud API uses HTTP Basic access authentication. An API user and a password is required to authenticate with the UpCloud API. The API user can be created in the UpCloud control panel.

Sample request header

GET /1.2/server HTTP/1.0
Host: api.upcloud.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Normal response

If authentication succeeds, the API returns an HTTP 200 OK response. A sample response header for a successful authentication:

HTTP/1.0 200 OK
Date: Mon, 01 Jan 2012 00:00:00 GMT
Server: Apache
Content-Length: 39042
Connection: close
Content-Type: application/json; charset=UTF-8

Error response

If authentication fails, the API returns an HTTP 401 error response. An example response for a failed authentication attempt:

HTTP/1.0 401 Authorization Required
Date: Mon, 01 Jan 2012 00:00:00 GMT
Server: Apache
WWW-Authenticate: Basic, realm="API"
Content-Length: 157
Connection: close
Content-Type: application/json; Charset=UTF-8
{
  "error": {
    "error_code": "AUTHENTICATION_FAILED",
    "error_message": "Authentication failed using the given username and password."
  }
}

Resource identifiers

UpCloud resources such as servers, storages and IP addresses are all referred to by unique identifiers. These identifiers are assigned when resources are created. Resources are always accessible by their unique identifiers as long as they exist on UpCloud.

The unique identifiers follow the version 4 format of the Universally unique identifier (UUID) standard.

Example UUID: 00104021-153d-4b0e-a4ec-730a5556442c.

To help differentiate between various types of resources, different types of resources have different UUID prefixes:

Resource type UUID prefix UUID example
Servers 00 00ff2a9e-2e38-449e-8dee-7986a127d034
Storages 01 01fe1129-b1cd-48e4-a488-c51874082818

Request and response data formats

In addition to HTTP requests, many API operations include exchange of data in the request or response body. This data is encoded either in JavaScript Object Notation (JSON) or eXtensible Markup Language (XML). The default encoding in JSON.

All examples in this document are in JSON format.

The data type definition is given in the HTTP request header. The Accept header defines the data type for requests and the Content-type header defines the data type in responses.

It is possible to send data in one format and receive in the other format.

A sample HTTP request header

POST /1.2/server HTTP/1.0
Host: api.upcloud.com
Authorization: Basic <base64-encoded authentication string>
Accept: application/json
Content-Type: application/json
Content-Length: <length>

Valid data type definitions:

  • application/json
  • application/xml

Sample response in JSON format:

HTTP/1.0 200 OK
Date: Tue, 03 Apr 2012 20:12:12 GMT
 Server: Apache
Content-Length: 713
Connection: close
Content-Type: application/json; charset=UTF-8
{
  "servers": {
    "server": [
      {
        "core_number": "2",
        "hostname": "server1.example.com",
        "license": 0,
        "memory_amount": "4096",
        "plan": "2xCPU-4GB",
        "plan_ipv4_bytes": "345354535",
        "plan_ipv6_bytes": "53543",
        "state": "started",
        "tags": {
          "tag": []
        },
        "title": "server1",
        "uuid": "001c397f-9b24-42ce-9977-07f16a592fb3",
        "zone": "fi-hel1"
      },
      {
        "core_number": "0",
        "hostname": "server2.example.com",
        "license": 0,
        "memory_amount": "512",
        "plan": "custom",
        "state": "started",
        "tags": {
          "tag": [
            "DEV",
            "Webserver"
          ]
        },
        "title": "server2",
        "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb316",
        "zone": "fi-hel1"
      }
    ]
  }
}

Sample response in XML format:

<?xml version="1.0" encoding="utf-8"?>
<servers>
  <server>
    <core_number>2</core_number>
    <hostname>server1.example.com</hostname>
    <license>0</license>
    <memory_amount>4096</memory_amount>
    <plan>2xCPU-4GB</plan>
    <plan_ipv4_bytes>345354535</plan_ipv4_bytes>
    <plan_ipv6_bytes>53543</plan_ipv6_bytes>
    <state>started</state>
    <tags>
    </tags>
    <title>server1</title>
    <uuid>001c397f-9b24-42ce-9977-07f16a592fb3</uuid>
    <zone>fi-hel1</zone>
  </server>
  <server>
    <core_number>0</core_number>
    <hostname>server2.example.com</hostname>
    <license>0</license>
    <memory_amount>512</memory_amount>
    <plan>custom</plan>
    <state>started</state>
    <tags>
      <tag>DEV</tag>
      <tag>Webserver</tag>
    </tags>
    <title>server2</title>
    <uuid>0077fa3d-32db-4b09-9f5f-30d9e9afb316</uuid>
    <zone>fi-hel1</zone>
  </server>
</servers>

Response codes

API responses use regular HTTP codes to indicate successful and failed requests.

Successful requests

Successful requests are responded with a response code between 200 and 299. Possible response codes are:

HTTP status Description
200 OK The request was successful.
201 Created The request resulted in the generation of a new resource such as a server or a storage.
202 Accepted The request resulted in the asynchronous creation or update of an existing resource.

Failed requests

Failed requests include a machine readable error code and a human readable error description in the response body. Invalid requests are responded with a response code between 400 and 499. Possible response codes are:

HTTP status Description
400 Bad request The request has invalid, unknown or missing attributes or the request cannot be properly parsed.
401 Unauthorized The request does not use or fails authentication.
402 Payment Required The request cannot be processed because of insufficient credits.
403 Forbidden The request accesses resources owned by some other user.
404 Not Found The request accesses resources that do not exist, but may have existed before.
405 Method not allowed The request uses an invalid HTTP verb, e.g. use POST on an operation that only accepts GET.
406 Not Acceptable The request has requirements given in the Accept headers that the API service cannot comply with.
409 Conflict The request cannot be processed because of a conflict between resources, e.g. trying to start an already started server.

API errors

Should there be a problem with the API service, a request is responded with an error code between 500 and 599. Possible response codes are:

HTTP status Description
500 Internal Server Error The request cannot be processed because of a temporary problem in the cloud service.
503 Service Unavailable The API service is not in use because of maintenance.

The error_code parameter defines the more specific error code. The error codes are defined under each operation in this API documentation.

The error_message parameter gives a human-readable error description that can include dynamic content such as UUIDs of resources in order to help track down the source of the error.

Example error response

HTTP/1.0 404 Not Found
{
  "error": {
    "error_message": "The server 00af0f73-7082-4283-b925-811d1585774b does not exist.",
    "error_code": "SERVER_NOT_FOUND"
  }
}