NAV
http

Introduction

Arkis currently offers a HTTP REST API wich is used by the Web UI. In this document you will find all API operations currently supported in the service and examples on how to execute them.

Docker API

Arkis is fully compatible with both Docker API and Docker Swarm API.

You can reach our Docker API through the following hostname:

https://api.arkis.io

Or to reach a specific Docker API version:

https://api.arkis.io/v1.18

However, in order to target your cluster running on Arkis, you must specify your cluster’s token by adding to all requests sent to this endpoints the following header:

X-Arkis-Cluster: ID CLUSTER_ID

or

X-Arkis-Cluster: NAME CLUSTER_NAME

Authentication

In order to be able to make requests to the Arkis API, you should first obtain a JSON Web Token for your account. For this, you can either use the API Key section on your dashboard, or use our authentication endpoints.

REST API

The Arkis REST API is reachable through the following hostname:

https://api.arkis.io

All requests to our REST API should be sent to this endpoint with the following Authorization header:

Authorization: JWT JSON_WEB_TOKEN_STRING

HTTP responses are given in JSON format, so the following Accept header is required for every API call:

Accept: application/json

Register / Sign in

POST /api/v1/auth/login HTTP/1.1
Host: api.arkis.io
Accept: application/json

Example

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImZvbGllYUBhcmtpcy5pbyIsImppdCI6ImJkM2QwYjYwLTBmMjEtMTFlNS1hN2RiLTFmNTM3MDNlOTVlOCIsImlhdCI6MTQzMzkwNzMyOH0.BQStzEqRlP-v0VUow6H6IppfzWHoONbHekWq3hG6YTk"
}

Create an account and returns the JSON Web Token of this account. If the account already exist and the credentials are corrects, returns the JSON Web Token of the existing account.

HTTP Request

POST /api/v1/auth/login

JSON Parameters

Parameter Description
email (required) A user provided account email
password (required) A user provided account password

Generate a new API token

GET /api/v1/account/new_token HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Example

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImZvbGllYUBhcmtpcy5pbyIsImppdCI6ImJkM2QwYjYwLTBmMjEtMTFlNS1hN2RiLTFmNTM3MDNlOTVlOCIsImlhdCI6MTQzMzkwNzMyOH0.BQStzEqRlP-v0VUow6H6IppfzWHoONbHekWq3hG6YTk"
}

Create an new JSON Web Token for your account, returns the newly created token.

HTTP Request

GET /api/v1/account/new_token

Change account password

PATCH /api/v1/account/change_password HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Change your account password.

HTTP Request

PATCH /api/v1/account/change_password

JSON Parameters

Parameter Description
old_password (required) Current password of the user
new_password (required) New password for the user
new_password_confirmation (required) New password confirmation

Returns a 204 status code if the password has been successfully updated.

Returns a 403 status code if the old_password parameter doesn’t match the user current password.

Change account email

PATCH /api/v1/account/change_email HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Change your account email address.

HTTP Request

PATCH /api/v1/account/change_email

JSON Parameters

Parameter Description
password (required) Current password of the user
new_email (required) New email address for the user

Returns a 204 status code if the email has been successfully updated.

Returns a 403 error code if the password parameter doesn’t match the user current password.

Cancel account

DELETE /api/v1/account/ HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Cancel your account.

HTTP Request

DELETE /api/v1/account/

JSON Parameters

Parameter Description
password (required) Current password of the user

Returns a 204 status code if the account has been successfully deleted.

Returns a 403 error code if the password parameter doesn’t match the user current password.

Profile

The user profile.

Attributes

Attribute Description
id A unique identifier for the use profile generated automatically on creation
user_id A unique identifier of the user the profile belongs to
fullname Fullname of the user
company Comparny of the user
location Location of the user
created_at The date and time when the profile was created
updated_at The date and time when the profile was updated last

Get your profile

GET /api/v1/account/profile HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Example

{
    "profile": {
        "id": 3,
        "fullname": "Saul Tigh",
        "company": "Cylons, Inc",
        "location": "Caprica",
        "created_at": "2015-06-10T16:11:14.149Z",
        "updated_at": "2015-06-10T16:11:14.149Z"
    }
}

Returns you user account profile.

HTTP Request

GET /api/v1/account/profile

Update your account profile

PATCH /api/v1/account/profile HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Example

{
    "profile": {
        "id": 3,
        "fullname": "Saul Tigh",
        "company": "Battlestar",
        "location": "Caprica",
        "created_at": "2015-06-10T16:11:14.149Z",
        "updated_at": "2015-08-10T16:11:14.149Z"
    }
}

Update you user account profile.

HTTP Request

PATCH /api/v1/account/profile

JSON Parameters

Parameter Description
fullname (optional) A user provided name for the profile
company (optional) A user provided company for the profile
location (optional) A user provided location for the profile

Cluster

A cluster is a group of nodes wich are on the same docker swarm cluster.

Attributes

Attribute Description
id A unique identifier (UUID) for the cluster generated automatically on creation
name A user provided name for the cluster
strategy Strategy for ranking the node (see Strategies)
state State of the cluster
state_message User-friendly informations about the state of the cluster
nodes_count The number of nodes present in the cluster
last_ping Date and time of the last time the cluster master node was contacted by Arkis
created_at The date and time when this cluster was created
updated_at The date and time when this cluster was updated last

List all clusters

GET /api/v1/clusters HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Example

{
    "meta": {
        "limit": 25,
        "offset": 0,
        "total_count": 2
    },
    "clusters": [{
        "state_message": "Create at least one node to work with this cluster",
        "id": "14813a80-19fa-11e5-a214-93ad3da1a84e",
        "name": "staging",
        "strategy": "binpack",
        "created_at": "2015-06-10T16:11:14.149Z",
        "updated_at": "2015-06-10T16:11:16.149Z",
        "nodes_count": 0,
        "last_ping": "2015-06-10T16:11:16.149Z",
        "state": "empty"
    }, {
        "state_message": "Cluster is deployed and ready",
        "id": "14813a81-19fa-11e5-a214-93ad3da1a84e",
        "name": "production",
        "strategy": "spread",
        "created_at": "2015-06-05T16:09:20.149Z",
        "updated_at": "2015-06-05T16:09:28.149Z",
        "nodes_count": 7,
        "last_ping": "2015-06-05T16:09:28.149Z",
        "state": "running"
    }]
}

List all clusters avalaible. Returns a list of Cluster objects.

HTTP Request

GET /api/v1/clusters

Query Parameters

Parameter Description
strategy Filter by strategy
state Filter by state
name Filter by name
limit Limits the number of returned objects (default: 25)
offset Limits starting with record number (default: 0)

Create a new cluster

Creates a new cluster.

HTTP Request

POST /api/v1/clusters

JSON Parameters

Parameter Description
name (required) A user provided name for the cluster
strategy (optional) A user provided strategy for the cluster (e.g. spread, binpack or random, default: spread)

Get an existing cluster

GET /api/v1/clusters/14813a80-19fa-11e5-a214-93ad3da1a84e/ HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Example

{
    "cluster": {
        "state_message": "Create at least one node to work with this cluster",
        "id": "14813a80-19fa-11e5-a214-93ad3da1a84e",
        "name": "grounds-production",
        "strategy": "spread",
        "created_at": "2015-06-10T16:11:14.149Z",
        "updated_at": "2015-06-10T16:11:13.149Z",
        "nodes_count": 0,
        "last_ping": "2015-06-10T16:11:13.149Z",
        "state": "empty"
    }
}

Get all the informations of a specific cluster.

HTTP Request

GET /api/v1/clusters/:cluster_id/

Query Parameters

Parameter Description
id The UUID of the cluster to retrieve

Update an existing cluster

PATCH /api/v1/clusters/14813a80-19fa-11e5-a214-93ad3da1a84e/ HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Example

{
    "cluster": {
        "state_message": "Create at least one node to work with this cluster",
        "id": "14813a80-19fa-11e5-a214-93ad3da1a84e",
        "name": "grounds-development",
        "strategy": "spread",
        "created_at": "2015-06-10T16:11:14.149Z",
        "updated_at": "2015-06-10T16:20:13.149Z",
        "nodes_count": 0,
        "last_ping": "2015-06-10T16:11:13.149Z",
        "state": "empty"
    }
}

Updates cluster details.

HTTP Request

PATCH /api/v1/clusters/:cluster_id/

JSON Parameters

Parameter Description
name (required) A user provided name for the cluster

Destroy a cluster

DELETE /api/v1/clusters/14813a80-19fa-11e5-a214-93ad3da1a84e/ HTTP/1.1
Host: api.arkis.io
Authorization: JWT JSON_WEB_TOKEN
Accept: application/json

Destroy all the nodes in a cluster and the cluster itself. This is irreversible.

HTTP Request

DELETE /api/v1/clusters/:cluster_id/

Query Parameters

Parameter Description
id The UUID of the cluster to retrieve

Returns a 204 status code if the cluster has been successfully deleted.

Upgrade a cluster

Upgrade docker daemon and swarm agent of all nodes of the cluster to the latest versions available on Arkis.

HTTP Request

POST /api/v1/clusters/:cluster_id/upgrade

Cluster State

States possible for a cluster.

Attributes

Attribute Description
empty Cluster waiting for node(s) to be created
unreachable Cluster’s master node is unreachable
deploying One or more node(s) are being deployed
upgrading One or more node(s) are being upgraded
running Cluster is running and reachable

Node

A node is a docker machine provided by a cloud provider where docker containers can be deployed.

Attribute Description
id A unique identifier (UUID) for the node generated automatically on creation
cluster_id The cluster UUID of which the node belongs
name A user provided name for the node (see Regions)
byon If the node is provided by Arkis or the user (bring your own node)
master Whether the node is the master of its cluster
labels A list of labels to identify the node when running containers (see Labels)
state The state of the node. See the below table for a list of possible states
state_message User-friendly informations about the state of the node
fqdn An automatically generated FQDN for the node
public_ip The public IP of the node
agent_cmd Command to install Arkis agent (only for byon node)
region The name identifier of the region where the node is deployed
node_size The name identifier of the node size object of this node (see Node sizes)
cpu Node number of CPUs
disk Node storage size in GB
memory Node memory in MB
last_ping Date and time of the last time the node was contacted by Arkis
docker_version Docker’s version used in the node
created_at The date and time when this node was created
deployed_at The date and time when this node was deployed
updated_at The date and time when this node was updated last

List all nodes of a cluster

List all nodes available for a cluster. Returns a list of Node objects.

HTTP Request

GET /api/v1/clusters/:cluster_id/nodes

Query Parameters

Parameter Description
state Filter by state
master Filter by master (true/false)
region Filter by region
node_size Filter by node size
byon Filter by byon (true/false)
labels Filter by a list of labels (e.g. [{ "region": "us-east", "environment": "production" }])

Create a new node for a cluster

Creates a new node for a cluster.

HTTP Request

POST /api/v1/clusters/:cluster_id/nodes

JSON Parameters

Parameter Description
name (required) Name of the node
master (optional) If the node will be the master of its cluster (default: false)
byon (optional) If the node will be provided by the user or by Arkis (default: false)
region (required) The name identifier of the region where the node will be deployed (see Regions)
node_size (required) Name identifier of the node size object desired for the node (see Node sizes)
labels (optional) List of labels to identify the node (see Labels)

Get an existing node

Get all the informations of a specific node.

HTTP Request

GET /api/v1/clusters/:cluster_id/nodes/:node_id/

Query Parameters

Parameter Description
cluster_id The UUID of the clusters wich the node to retrieve belongs to
node_id The UUID of the node to retrieve

Destroy a node

Removes a node from the cluster and destroys the node itself. This is irreversible.

HTTP Request

DELETE /api/v1/clusters/:cluster_id/nodes/:node_id/

Query Parameters

Parameter Description
cluster_id The UUID of the clusters wich the node to retrieve belongs to
node_id The UUID of the node to retrieve

Update an existing node

Updates node details and applies the changes automatically.

HTTP Request

PATCH /api/v1/clusters/:cluster_id/nodes/:node_id

JSON Parameters

Parameter Description
name (required) Name of the node
master (optional) If the node will be the master of its cluster (default: false)
labels (optional) List of labels to identify the node (see Labels)

Upgrade an existing node

Upgrade docker daemon and swarm agent on an existing node to its cluster versions.

HTTP Request

POST /api/v1/clusters/:cluster_id/nodes/:node_id/upgrade

Node State

States possible for a node.

Attributes

Attribute Description
unreachable Node is unreachable
deploying Node is being deployed
upgrading Node is being upgraded
running Node is running and reachable

Labels

Labels are key/value pairs associated to particular nodes.

When creating a container, the user can select a subset of nodes that should be considered for scheduling by specifying one or more sets of matching key/value pairs.

This approach has several practical use cases such as:

See Docker Swarm Filters.

Label Object

A label object is represented as a simple json object.

Example

{
    "labels": {
        "environment": "production",
        "project": "my_app"
    }
}

Node Sizes

A node size is a representation of an instance size supported in a certain region.

Attributes

Attribute Description
name An name identifier for the node size
label A user-friendly name for the node size
cpu Number of CPU’s core
disk Storage size in GB
memory Memory in MB
regions A list of regions name identifier where the node can currently be deployed (see Regions)
available Whether the node size is currently available for new deployments

List all node sizes

List all node sizes currently supported. Returns a list of NodeSize objects.

HTTP Request

GET /api/v1/nodesizes

Query Parameters

Parameter Description
region Filter by region name
available Filter by availability (true/false)

Get an existing node size

Get all informations of a specific node size.

HTTP Request

GET /api/v1/nodesize/:name/

Query Parameters

Parameter Description
name The name identifier of the node size to retrieve

Regions

A region is a representation of an entire or a subset of a data center. It contains one and more node sizes.

Attributes

Attribute Description
name An identifier for the region
label A user-friendly name for the region
available Whether the region is currently available for new deployments
node_sizes A list of node size name identifier available in the region (see Node sizes)

List all regions

List all regions currently supported. Returns a list of Region objects.

HTTP Request

GET /api/v1/regions

Query Parameters

Parameter Description
node_size Filter by node size name (see Node sizes)
available Filter by availability (true/false)

Get an existing region

Get all informations of a specific region.

HTTP Request

GET /api/v1/region/:name/

Query Parameters

Parameter Description
name The name identifier of the region to retrieve

Errors

The Arkis API uses the following error codes:

Error Code Meaning
400 Bad Request – There’s a problem in the content of your request.
401 Unauthorized – Your password or API Key is wrong or revoked.
403 Forbidden – The action or resource requested is forbidden.
404 Not Found – The specified resource could not be found.
406 Not Acceptable – You requested a format that isn’t json.
409 Conflict – The action can’t currently be treated.
500 Internal Server Error – We had a problem with our server. Please try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Validation Errors

Example

{
    "errors": [
        {
            "message": "Validation len failed",
            "type": "Validation error",
            "path": "password",
            "value": "Validation len failed"
        }
    ]
}

When you receive a 400 Bad Request error, you will find in the response body and array of validation errors to help you identify what is wrong in your request.

Attributes

Attribute Description
message An error message
type The type of the validation error
path The field that triggered the validation error
value The value that generated the error
http