AMS Rest API

All the communications between AMS and its clients happen using a
RESTful API over HTTP which is then encapsulated over either TLS for
remote operations or a unix socket for local operations

Not all REST API endpoints require authentication:

  • GET to / is allowed for everyone
  • GET to /1.0 is allowed for everyone
  • GET to /1.0/version is allowed for everyone

Some endpoints require an additional authentication token to ensure
that the requester is authorized to access the resource:

  • GET to /1.0/artifacts
  • PATCH to /1.0/containers/

API versioning

The details of a version of the api can be retrieved using GET /<version>.
For example GET /1.0

The reason for a major API bump is if the API breaks backward compatibility.

Feature additions done without breaking backward compatibility only
result in addition to api_extensions which can be used by the client
to check if a given feature is supported by the server.

Return values

There are three standard return types:

  • Standard return value
  • Background operation
  • Error

Standard return value

For a standard synchronous operation, the following dict is returned:

{
    "type": "sync",
    "status": "Success",
    "status_code": 200,
    "metadata": {}                          # Extra resource/action specific metadata
}

HTTP code must be 200.

Background operation

When a request results in a background operation, the HTTP code is set to 202 (Accepted)
and the Location HTTP header is set to the operation URL.

The body is a dict with the following structure:

{
    "type": "async",
    "status": "OK",
    "status_code": 100,
    "operation": "/1.0/containers/<id>",                    # URL to the background operation
    "metadata": {}                                          # Operation metadata (see below)
}

The operation metadata structure looks like:

{
    "id": "c6832c58-0867-467e-b245-2962d6527876",           # UUID of the operation
    "class": "task",                                        # Class of the operation (task, websocket or token)
    "created_at": "2018-04-02T16:49:36.341463206+02:00",    # When the operation was created
    "updated_at": "2018-04-02T16:49:36.341463206+02:00",    # Last time the operation was updated
    "status": "Running",                                    # String version of the operation's status
    "status_code": 103,                                     # Integer version of the operation's status (use this rather than status)
    "resources": {                                          # Dictionary of resource types (container, snapshots, images) and affected resources
      "containers": [
        "/1.0/containers/3apqo5te"
      ]
    },
    "metadata": null,                                       # Metadata specific to the operation in question (in this case, nothing)
    "may_cancel": false,                                    # Whether the operation can be canceled (DELETE over REST)
    "err": ""                                               # The error string should the operation have failed
}

The body is mostly provided as a user friendly way of seeing what’s
going on without having to pull the target operation, all information in
the body can also be retrieved from the background operation URL.

Error

There are various situations in which something may immediately go
wrong, in those cases, the following return value is used:

{
    "type": "error",
    "error": "Failure",
    "error_code": 400,
    "metadata": {}                      # More details about the error
}

HTTP code must be one of of 400, 401, 403, 404, 409, 412 or 500.

Status codes

The AMS REST API often has to return status information, be that the
reason for an error, the current state of an operation or the state of
the various resources it exports.

To make it simple to debug, all of those are always doubled. There is a
numeric representation of the state which is guaranteed never to change
and can be relied on by API clients. Then there is a text version meant
to make it easier for people manually using the API to figure out what’s
happening.

In most cases, those will be called status and status_code, the former
being the user-friendly string representation and the latter the fixed
numeric value.

The codes are always 3 digits, with the following ranges:

  • 100 to 199: resource state (started, stopped, ready, …)
  • 200 to 399: positive action result
  • 400 to 599: negative action result
  • 600 to 999: future use

List of current status codes

Code Meaning
100 Operation created
101 Started
102 Stopped
103 Running
104 Cancelling
105 Pending
106 Starting
107 Stopping
108 Aborting
109 Freezing
110 Frozen
111 Thawed
200 Success
400 Failure
401 Cancelled

Recursion

To optimize queries of large lists, recursion is implemented for collections.
A recursion argument can be passed to a GET query against a collection.

The default value is 0 which means that collection member URLs are
returned. Setting it to 1 will have those URLs be replaced by the object
they point to (typically a dict).

Recursion is implemented by simply replacing any pointer to an job (URL)
by the object itself.

Async operations

Any operation which may take more than a second to be done must be done
in the background, returning a background operation ID to the client.

The client will then be able to either poll for a status update or wait
for a notification using the long-poll API.

Notifications

A websocket based API is available for notifications, different notification
types exist to limit the traffic going to the client.

It’s recommended that the client always subscribes to the operations
notification type before triggering remote operations so that it doesn’t
have to then poll for their status.

PUT vs PATCH

The AMS API supports both PUT and PATCH to modify existing objects.

PUT replaces the entire object with a new definition, it’s typically
called after the current object state was retrieved through GET.

To avoid race conditions, the Etag header should be read from the GET
response and sent as If-Match for the PUT request. This will cause AMS
to fail the request if the object was modified between GET and PUT.

PATCH can be used to modify a single field inside an object by only
specifying the property that you want to change. To unset a key, setting
it to empty will usually do the trick, but there are cases where PATCH
won’t work and PUT needs to be used instead.

Authorization

Some operation may require a token to be included in the HTTP Authorization
header like this:

  • Authorization: bearer

No matter if the request is already authenticated using a trusted
certificate. If the token is not valid, the request is rejected by the
server. This ensures that only authorized clients can access those endpoints

File upload

Some operation require uploading a payload. To prevent the difficulties
of handling multipart requests, another solution has been taken: A unique file is uploaded and its bytes are included in the body of the request. Some metadata associated with the file is included in extra HTTP headers:

  • X-AMS-Fingerprint: fingerprint of the addon payload being added
  • X-AMS-Request: metadata for the payload. This is a JSON, specific for
    the operation.

API structure

API details

/1.0/

GET

  • Description: Server configuration
  • Authentication: guest, untrusted or trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Return general information of the server
  • Return: Dict representing server state

Return value (if trusted):

{
    "api_extensions": [],                           # List of API extensions added after the API was marked stable
    "api_status": "stable",                         # API implementation status (one of, development, stable or deprecated)
    "api_version": "1.0",                           # The API version as a string
    "auth": "trusted",                              # Authentication state, one of "guest", "untrusted" or "trusted"
    "public": false,                                # Whether the server should be treated as a public (read-only) remote by the client
}

/1.0/addons

GET

  • Description: List of addons
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Fetch all available addons from the database
  • Return: A list with the available addons

Return value:

[
    "/1.0/addons/foo",
    "/1.0/addons/bar"
]

POST

  • Description: Create a new addon
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Read addon metadata and package from request
  • Save addon metadata into the database
  • Return: background operation or standard error

A payload is uploaded. X-AMS-Request header is comprised of:

{
    "name": "myaddon"
}

/1.0/addons/<name>

GET

  • Description: Addon information
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Load addon metadata from the database
  • Return: Dict including addon details

Output:

{
    "name": "myaddon",
    "version": {
        "number": 0,
        "fingerprint": "e25f3e3bcead096461d89d8ab7043f14bdb1ecd39",
        "size": 456676,
        "created_at": "2015-06-09T19:07:24.379615253-06:00"
    }
}

DELETE

  • Description: Delete the addon
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Delete addon metadata from the database
  • Return: background operation or standard error

Input (none at present):

{
}

PATCH (ETag supported)

  • Description: Update addon metadata and creates a new addon version for it
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Read addon metadata and package from request
  • Validate addon name and payload fingerprint lenghts
  • Save artifact in local storage
  • Update artifact metadata in the database
  • Return. background operation or standard error

A payload is uploaded. X-AMS-Request header is comprised of:

{
    "name": "myaddon"
}

/1.0/addons/<name>/<version>

DELETE

  • Description: Delete specific version of an addon
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Remove cached artifacts from the addon version to be deleted
  • Remove the addon version metadata from the database
  • Return: background operation or standard error

Input (none at present):

{
}

/1.0/applications

GET

  • Description: List of applications
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Retrieve all applications from the database
  • Return: list of URLs for applications this server publishes

Return value:

{
    "/1.0/applications/foo",
    "/1.0/applications/bar"
}

POST

  • Description: Create a new application
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Read application metadata and package from request
  • Select image version to be used for the application
  • Select addons to be used for the application
  • Store application package in the local artifact storage
  • Save application metadata in the database
  • Run bootstrap process for the application
  • Return: background operation or standard error

Input:

{
    "name": "candy",
    "image": "default",
    "instance_type": "a2.3",
    "boot_activity": "com.canonical.candy.GameApp",
    "required_permissions": [
        "android.permission.WRITE_SETTINGS",
        "android.permission.READ_PHONE_STATE",
        "android.permission.SEND_SMS",
    ],
    "addons": [
        "foo",
        "bar"
    ]
}

/1.0/applications/<id>

GET

  • Description: Application information
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Load the application metadata from the database
  • Return: dict of the application configuration and current state.

Output:

{
    "app_id": "befpvs2hmss5804ta7hg",
    "name": "candy",
    "status_code": 2,
    "status": "ready",
    "instance_type": "a2.3",
    "boot_package": "com.canonical.candy",
    "boot_activity": "com.canonical.candy.GameApp",
    "required_permissions": null,
    "parent_image_id": "befoo1ahmss5804ta720",
    "published": true,
    "versions": [
    {
        "number": 0,
        "parent_image_version": 0,
        "status_code": 3,
        "status": "active",
        "published": true,
        "addons": [
        {
            "Name": "debugger",
            "Version": 0
        }
        ],
        "created_at": 1537187824,
        "extra_data": null
    }
    ],
    "addons": [
    "debugger"
    ],
    "created_at": 0,
    "extra_data": {}
}

PATCH (ETag supported)

  • Description: Update existing application with a new package
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Read application metadata and package from request
  • Store application package in local artifacts storage
  • Create a new application version
  • Run bootstrap process for the application version
  • Return: standard return value or standard error

A payload is uploaded. X-AMS-Request header is empty

DELETE

  • Description: Remove the application
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Delete application related containers
  • Delete application related artifacts
  • Delete application from database
  • Return: background operation or standard error

Input (none at present):

{
}

/1.0/applications/<id>/<version>

DELETE

  • Description: Removes an application version
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Check that the version is not already deleted
  • Mark the version as deleted and not published
  • If the application version is currently being bootstrapped, stop the process
  • Remove the version image if needed
  • Return: background operation or standard error

Input (none at present):

{
}

PATCH

  • Description: Publish/unpublish an application version
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Set application version as published
  • Return: background operation or standard error

Input:

{
    "published": true
}

/1.0/certificates

GET

  • Description: List of trusted client certificates
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • List trusted certificates
  • Return: list of URLs for certificates this server trusts

Return value:

{
    "/1.0/certificates/abckaliar",
    "/1.0/certificates/koelaidfd"
}

POST

  • Description: Registers a new client certificate as trusted
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Look for certificate included in TLS request
  • Look for certificate included into body
  • Save provided certificate to the database, if found
  • Return: background operation or standard error

Input:

{
    "certificate": "MIIFUTCCAzmgAw...xjKoUEEQOzJ9",  # Base64 certificate content without header and footer
    "trust-password": "aahhdjiks9",                  # Only needed if not using an already trusted client 
                                                     # certificate in the SSL request or using the local unix socket
}

/1.0/certificates/<id>

GET

  • Description: Retrieve information about a stored certificate
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Retrieve certificate details from the database
  • Return: dict of the certificate information

Output:

{
    "certificate": "-----BEGIN CERTIFICATE-----
MIIFUTCCAzmgAw
...
xjKoUEEQOzJ9
-----END CERTIFICATE-----",  # Base64 certificate content, including header and footer
    "fingerprint": "aadfaoieu84mja984580480jfkl"
}

DELETE

  • Description: Remove specified certificate from the trusted list
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Remove certificate from the database
  • Return: background operation or standard error

Input (none at present):

{
}

/1.0/containers

GET

  • Description: Retrieve list of all available containers
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • List containers from the database
  • Return: list of URLs for containers this server publishes

Return value:

[
    "/1.0/containers/foo",
    "/1.0/containers/bar"
]

POST

  • Description: Launch a new container
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Get the correct application version of the container
  • Add container to the database
  • Internal scheduler decides which node the container should
    be placed on
  • Create the container on the selected LXD node
  • Start the container
  • Return: background operation or standard error

Input:

{
    "app_id": "chobyxar",                       # Identifier of the application this container belongs to
    "app_version": 0,                           # Version of the application this container uses
    "userdata": "",                             # Additional data to be put into the container when bootstrapped
    "services": [                               # List of network services the container provides
        {
            "port": 22,                         # Network port the service listens on
            "protocol": "tcp",                  # Network protocol the services uses (udp, tcp)
            "expose": false,                    # True to expose the service on the public endpoint or false to keep it on the private one
        },
    ],
    "config": {                                 # Config parameters included in created container
        "platform": "arg",
        "boot_package": "com.my.app",
        "boot_activity": "com.my.app.Activity"
    }
}

/1.0/containers/<id>

GET

  • Description: Container information
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Load the container from the database
  • Return: dict of the container configuration and current state.

Output:

{
    "id": "beg9luahmss2qsgcovpg",
    "name": "ams-beg9luahmss2qsgcovpg",
    "type": "regular",
    "status_code": 4,
    "status": "ready",
    "node": "lxd0",
    "app_id": "befpvs2hmss5804ta7hg",
    "app_version": 0,
    "created_at": 1537252089,
    "address": "192.168.100.13",
    "public_address": "147.75.56.44",
    "services": [
    {
        "port": 9995,
        "node_port": 10011,
        "protocols": [
        "tcp"
        ],
        "expose": true
    }
    ],
    "stored_logs": [
        "container.log",
        "system.log",
        "android.log"
    ]
}

DELETE

  • Description: remove the container
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Terminate container on the node
  • Delete the container from the database
  • Return: background operation or standard error

Input (none at present):

{
}

/1.0/config

GET

  • Description: List all configuration items
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • List all configuration items
  • Return: Dict with the current configuration

Output:

{
   "config": {
        "application.addons": "debugger",
        "application.auto_publish": "false",
        "application.max_published_versions": "3",
        "experimental.cpu.limit_mode": "pinning",
        "scheduler.strategy": "spread"
    }
}

/1.0/events

This URL isn’t a real REST API endpoint, instead doing a GET query on it
will upgrade the connection to a websocket on which notifications will
be sent.

GET (?type=operation,logging)

  • Description: websocket upgrade
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Return a websocket connection to receive server events
  • Return: none (never ending flow of events)

Supported arguments are:

  • type: comma separated list of notifications to subscribe to (defaults to all)

The notification types are:

  • operation (notification about creation, updates and termination of all background operations)
  • logging (every log entry from the server)
  • lifecycle (container lifecycle events)

This never returns. Each notification is sent as a separate JSON dict:

{
    "timestamp": "2015-06-09T19:07:24.379615253-06:00",                # Current timestamp
    "type": "operation",                                               # Notification type
    "metadata": {}                                                     # Extra resource or type specific metadata
}
{
    "timestamp": "2016-02-17T11:44:28.572721913-05:00",
    "type": "logging",
    "metadata": {
        "context": {
            "ip": "@",
            "method": "GET"
            "url": "/1.0/containers/xen/snapshots",
        },
        "level": "info",
        "message": "handling"
    }
}

/1.0/images

GET

  • Description: List available images
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • List the images available in the database
  • Return: list of URLs of the images in the cluster

Return value:

[
    "/1.0/images/foo",
    "/1.0/images/bar"
]

POST

  • Description: Registers a new image
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Validate metadata and image
  • Store image in local artifact storage
  • Create a new image version
  • Upload the image to the LXD cluster
  • Return: background operation or standard error

A payload is uploaded. X-AMS-Request header is comprised of:

{
    "name": "myimage"
}

/1.0/images/<id>

GET

  • Description: Load image information
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Get the image from the database
  • Return: dict with the image information.

Output:

{
    "id": "bdk525ilcgl6d1i1sbv0",
    "name": "myimage",
    "status_code": 3,
    "status": "active",
    "versions": [
        {
            "version": 0,
            "fingerprint": "dbbbb0d87b645b882a949bfe25f3e3bcead096461d89d8ab7043f14bdb1ecd39",
            "size": 392944268,
            "created_at": 1533563158,
            "status_code": 3,
            "status": "active"
        }
    ]
}

PATCH (ETag supported)

  • Description: Updates an existing image
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Validate metadata and image
  • Save image in the local artifact storage
  • Generate a new image version
  • Upload image to the LXD cluster
  • Return: standard return value or standard error

A payload is uploaded. X-AMS-Request header is comprised of:

{
    "name": "myimage"
}

DELETE

  • Description: Remove an existing image
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Mark image as deleted in the database
  • Remove image artifacts and metadata
  • Delete a single version of an existing image
  • Return: background operation or standard error

Input (none at present):

{
}

/1.0/images/<id>/<version>

DELETE

  • Description: Deletes a single version of an image
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Remove image from the local artifacts store
  • If the version is the last one of the image, remove the image
    otherwise remove the version from database
  • Return: background operation or standard error

Input (none at present):

{
}

/1.0/nodes

GET

  • Description: List available nodes
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • List available nodes from the database
  • Return: list of nodes in the cluster

Return value:

[
    {
        "name": "lxd0",
        "address": "172.31.23.150",
        "public_address": "34.250.180.153",
        "network_bridge_mtu": 0,
        "cpus": 1,
        "cpu_allocation_rate": 4,
        "memory": "3GB",
        "memory_allocation_rate": 2,
        "status_code": 4,
        "status": "online",
        "is_master": true
    },
    {
        "name": "lxd1",
        "address": "172.31.23.151",
        "public_address": "34.250.180.155",
        "network_bridge_mtu": 0,
        "cpus": 1,
        "cpu_allocation_rate": 4,
        "memory": "3GB",
        "memory_allocation_rate": 2,
        "status_code": 4,
        "status": "online",
        "is_master": false
    }
]

POST

  • Description: Add a LXD node to the cluster
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Validate node metadata
  • Save node in the database
  • Add node to the existing LXD cluster or bootstrap a new one
  • Return: background operation or standard error

Input:

{
    "name": "lxd0",
    "address": "172.31.23.150",
    "public_address": "34.250.180.153",
    "trust_password": "adjisj85nfiajlls",
    "network_bridge_mtu": 1500,
    "storage_device": "/dev/sda",
    "cpus": 2,
    "cpu_allocation_rate": 4,
    "memory": "3GB",
    "memory_allocation_rate": 2
}

/1.0/nodes/<name>

GET

  • Description: Load node information
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Load node from the database
  • Return: dict of the node configuration and current state.

Output:

{
    "name": "lxd0",
    "address": "172.31.23.150",
    "public_address": "34.250.180.153",
    "network_bridge_mtu": 0,
    "cpus": 1,
    "cpu_allocation_rate": 4,
    "memory": "3GB",
    "memory_allocation_rate": 2,
    "status_code": 4,
    "status": "online",
    "is_master": true
}

PATCH (ETag supported)

  • Description: Update node configuration
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Update node metadta in the database
  • Return: standard return value or standard error

Input:

{
    "public_address": "34.250.180.153",
    "cpus": 1,
    "cpu_allocation_rate": 4,
    "memory": "3GB",
    "memory_allocation_rate": 2
}

DELETE

  • Description: Remove the node from the cluster
  • Authentication: trusted
  • Operation: async
  • Cancellable: no
  • Steps:
  • Remove exiting container from the node
  • Remove node from the LXD cluster
  • Delete node from the database
  • Return: background operation or standard error

Input:

{
    "force": yes
}

/1.0/operations

GET

  • Description: list of operations
  • Authentication: trusted
  • Operation: sync
  • Return: list of URLs for operations that are currently going on/queued

Return:

[
    "/1.0/operations/c0fc0d0d-a997-462b-842b-f8bd0df82507",
    "/1.0/operations/092a8755-fd90-4ce4-bf91-9f87d03fd5bc"
]

/1.0/operations/<uuid>

GET

  • Description: Load operation information. If the service is deployed as
    a cluster of several instances, the operation is held in one of them. In
    case the request reaches a different instance of the one holding the
    operation, the information is taken internally from the right one.
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Get the operation from the service instance where request gets
  • If not found, get the operation from the service instance where it is
  • Return: dict representing a background operation

Return:

{
    "id": "b8d84888-1dc2-44fd-b386-7f679e171ba5",
    "class": "token",                                                                       # One of "task" (background task), "websocket" (set of websockets and crendentials) or "token" (temporary credentials)
    "created_at": "2016-02-17T16:59:27.237628195-05:00",                                    # Creation timestamp
    "updated_at": "2016-02-17T16:59:27.237628195-05:00",                                    # Last update timestamp
    "status": "Running",
    "status_code": 103,
    "resources": {                                                                          # List of affected resources
        "images": [
            "/1.0/images/54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473"
        ]
    },
    "metadata": {                                                                           # Extra information about the operation (action, target, ...)
        "secret": "c9209bee6df99315be1660dd215acde4aec89b8e5336039712fc11008d918b0d"
    },
    "may_cancel": true,                                                                     # Whether it's possible to cancel the operation (DELETE)
    "err": ""
}

DELETE

  • Description: Cancel an operation. Calling this will change the state to
    “cancelling” rather than actually removing the entry. If the service is deployed as
    a cluster of several instances, the operation is held in one of them. In
    case the request reaches a different instance of the one holding the
    operation, the information is taken internally from the right one.
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Search for the operation in the service instance where request gets
  • If not found, get the operation from the service instance where it is
  • Return: standard return value or standard error

Input (none at present):

{
}

HTTP code for this should be 202 (Accepted).

/1.0/operations/<uuid>/wait

GET (optional ?timeout=30)

  • Description: Wait until an operation reaches a final status
  • Authentication: trusted
  • Operation: sync
  • Cancellable: yes
  • Steps:
  • Does not return anything until operation reaches a final status
  • Return: dict of the operation after it’s reached its final state

Input (wait indefinitely for a final state): no argument

Input (similar but times out after 30s): ?timeout=30

/1.0/operations/<uuid>/websocket

GET (?secret=SECRET)

  • Description: This connection is upgraded into a websocket connection
    speaking the protocol defined by the operation type. For example, in the
    case of an exec operation, the websocket is the bidirectional pipe for
    stdin/stdout/stderr to flow to and from the process inside the container.
    In the case of migration, it will be the primary interface over which the
    migration information is communicated. The secret here is the one that was
    provided when the operation was created. Guests are allowed to connect
    provided they have the right secret.
  • Authentication: guest or trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • Upgrade http request to a websocket connection
  • Return: websocket stream or standard error

/1.0/tasks

GET

  • Description: All configuration items
  • Authentication: trusted
  • Operation: sync
  • Cancellable: no
  • Steps:
  • List all tasks from the database
  • Return: Dict with the current configuration

Output:

{
    "id": "beg9luahmss2qsgcovq0",
    "status": "error",
    "object_id": "beg9luahmss2qsgcovpg",
    "object_type": "container"
}

/1.0/version

GET

  • Description: Load status information about the service
  • Authentication: guest
  • Operation: Sync
  • Cancellable: no
  • Steps:
  • Load all configuration items from the database
  • Return: Version number

Return:

{
    "version": "0.1-0"
}