About the Cloud Server API

We provide an API (Application Programming Interface) for customers who need to control their Bytemark services automatically. You can use this facility to create and delete new servers.

We are finishing up documentation so that you’ll be able to register domain names and keep track of your billing as well.

If you’re not a programmer you probably just want to use the Bytemark Panel instead.

Our API docs have two sections:

• Cloud servers API
• Authentication API will apply to many Bytemark services

Cloud Servers API

We used to sell our Cloud Server product as ‘BigV’, and referred to those servers as ‘virtual machines’. You will still see those referenced as such throughout the API documents. We will eventually remove these references and rename the end points, but we won’t break your code.

The API is RESTful and so the HTTP method you use determines the type of action you’re performing:

• GET – Reads existing data.
• POST – Creates some new data.
• PUT – Updates some existing data.
• DELETE – Deletes some data.

It’s also worth noting that our implementation of PUT works like the (newer) PATCHmethod; it will only update the attributes supplied.

API URL

The endpoint (URL) for our Cloud Servers is currently: https://uk0.bigv.io and all URLs in this section are relative to that URL.

Data format

The API uses the JSON data format. All requests should set Accept and Content-Typeheaders appropriately. If Content-Type is set incorrectly, POST and PUT will not work.

POST https://uk0.bigv.io/accounts/{account-id}/groups HTTP/1.1
Content-type: application/json
Accept: application/json

Nested URLs

Older style endpoints have nested parameters in URLs. Newer style endpoints do not require this nesting and take additional parameters in the query string:

account_id
account_name
group_id
group_name
vm_id
vm_name
user_id
user_name
privilege_id

Newer style endpoints are only available for GET requests. Non-nested POST/PUT/DELETE endpoints are in development.

# Old style
GET /accounts/{account-id}/groups/{group-id}
GET /accounts/{account-id}/groups/{group-id}/virtual_machines
GET /accounts/{account-id}/groups/{group-id}/virtual_machines/{vm-id}/discs

# New style
GET /groups/{group-id}
GET /virtual_machines?group_id={group-id}
GET /discs?vm_id={vm-id}

HTTP Status Codes

Sometimes you will have privileges to use GET on a resource, but will get a 403 if you try to PUT/POST/DELETE to it without having appropriate permissions. If you do not have privileges to GET on the resource, then GET/PUT/POST/DELETE will all return HTTP response code: 404 Not Found.

Requests for unknown resources return HTTP response code: 404 Not Found.

Unexpected errors or server-side problems will return HTTP response code: 500.

The body content for PUT and POST requests is a JSON hash of attribute => value (e.g., {"username":"something"}) for the attributes you would like to update. Unknown attributes are silently discarded. Bad values for known attributes will cause the request to fail with HTTP response code: 400. In this case, the response body will be a JSON hash of attr => [error1, …].

Successful POST requests return HTTP response code: 201 (200 for PUT) and the response body will be a JSON hash describing the newly created (or updated) resource.

Successful GET requests return HTTP 200 and the response body is a JSON hash or array of hashes describing the resource, or resources, requested.

Successful DELETE requests return HTTP 204 (No Content). If a delete fails, a 400response with a text/plain or application/json body (whichever is most appropriate) will be returned with the reason.

Authentication

All API requests require a valid session token obtained from https://auth.bytemark.co.uk (exceptions to this are Definitions and the session requests below).

Sessions are valid for five minutes from the point of issue. Requests to read the session (GET /session/{session-id}) or successfully authenticated API requests extend this by five minutes.

Create session

POST https://auth.bytemark.co.uk/session HTTP/1.1
Content-Type: application/json
Accept: text/plain

Parameters

{
  "username"  : "my-username-here",
  "password"  : "my-password-here",
  "yubikey"   : "my-optional-yubikey-otp-here"
}

Curl

curl  -H "Content-type: application/json" \
    -X POST -d \
           '{ "username"  : "my-username-here", "password"  : "my-password-here" }' \
    https://auth.bytemark.co.uk/session

WGet

wget  --header "Content-type: application/json" \
    --post-data '{ "username"  : "my-username-here", "password"  : "my-password-here" }' \
    https://auth.bytemark.co.uk/session

Response

Assuming username, password and yubikey (if provided) are correct, a 200 OK response will be returned with a text/plain body. This is the session ID.

text/plain: Session ID

Read session

Gets session information, or verify that a session is valid.

GET https://auth.bytemark.co.uk/session/{session-id} HTTP/1.1
Accept: application/json

Response

This returns a 404 if the session does not exist, and 200 with a JSON body if it does.

{ 
  "username"          : "my-username-here",
  "factors"           : ["password", "yubikey", ...],
  "group_memberships" : ["group1", "group2"]
}

• The username is the same as the POST /session request that created the session.
• factors is an array of strings describing the credentials the user supplied to acquire the session — password and yubikey are the only ones currently.
• A user’s groups may be altered during the lifetime of a session, so if you care about group membership, you should check every time.

Each time you GET the session with this endpoint; the session expiry time is extended by five minutes.

Authenticated requests

API requests are authenticated by sending valid session token using the Authorization header RFC6750 token

GET {api-url} HTTP/1.1
Authorization: Bearer {session-id}

Requests without a valid session token should return a HTTP 401 status.