Brightbox API Documentation 1.0.0beta
Introduction
Welcome to the Brightbox Cloud API! The API allows you to programmatically control the computing resources available to your account.
It currently allows management of the following resources:
- Servers - virtualised compute instances in a range of capabilities (Server Types)
- Server Groups - collections of Servers
- Load Balancers - for dividing network traffic across multiple Servers
- Cloud IPs - dynamic public IP addresses that can be moved between Servers or Load Balancers
- Database Servers - hosted SQL databases (MySQL or Postgres)
- Database Snapshots - snapshots of Database Servers taken from an SQL Instance
- Firewall Policies - collections of Firewall Rules applied to a Server Group
- Firewall Rules - a rule to apply to network traffic as part of a Firewall Policy
- Images - uploaded disk images or snapshots made from existing services
In addition it allows management of some aspects of your User, Account, Collaborations and API client details.
Requirements to use the service
In order to use the Brightbox Cloud service and the API you must have a valid User profile and an Account which has been successfully verified.
New users can sign up to the service at https://manage.brightbox.com
If you were a user during the beta period of the service, you should have received instructions about how to upgrade your profile and account details to gain full access.
General concepts
Users and Accounts
In the Brightbox Cloud we differentiate between a User, a person who uses the site, and an Account which is where costs and resources are managed.
A User must agree to the terms and conditions to use the service. An Account must be setup with a valid payments card and be verified by telephone.
At the present time we are limiting each User to having one Account. This may change in the future to allow multiple users to manage one Account and a User having several Accounts.
The best way to manage your user and account details are using the management control panel at https://manage.brightbox.com
Regions and Zones
We divide our service into two geographical layers. Regions are larger areas which contain several Zones. Zones are roughly equivalent to data centres. Zones however are completely independent of each other.
The Brightbox API is currently regional. So you can interact with several Zones through the API.
Resource IDs
All resources have a unique and immutable ID. These consist of a three letter code, a dash and approximately five alphanumeric characters. The characters are actually a number encoded as Base36 to save on typing. As such the number range may expand and become longer.
API tools and client libraries
Whilst the Brightbox Cloud API is already pretty simple to use we already provide a number of tools to help. Some of these may help you rather than having to work against the API directly.
Brightbox CLI
We provide a set of command line tools to access and manage most of the resources. Details are available at the documentation site.
The CLI tools are available as either a Ruby gem or a Ubuntu/Debian package.
Fog (Ruby Library)
Fog is a cloud abstraction library for Ruby that standardise some of the details of different cloud providers APIs.
Support for the Cloud API in Fog is officially maintained by Brightbox.
Our CLI tools use Fog.
Apache Libcloud (Python Library)
Libcloud is a standard Python library that abstracts away differences among multiple cloud provider APIs. We added support for our API to libcloud, which is now included upstream.
Chef/Knife plugin
rubiojr kindly wrote a Knife plugin to allow you to use Chef to provision Brightbox cloud servers in one line.
Blog post covering: Bootstrapping an Ubuntu Image in Brightbox’s Cloud using knife
API concepts
API endpoint URLs
All communication with the API is required to be secured using SSL so the protocol must always be HTTPS.
The API endpoint URL for the GB1 region is: api.gb1.brightbox.com
API versioning
The Brightbox Cloud API uses semantic versioning
The current version of the API is 1.0.0beta but the URL only includes the major and minor parts of the version number
To use a particular version of the API, add it to the base API endpoint URL e.g api.gb1.brightbox.com/1.0/
DateTime and Timezone
All Times are stored and reported in UTC. The ISO8601 format (e.g. 2011-09-13T16:09:54Z
) is used throughout the API. The DateTimes are returned as strings since JSON does not have a DateTime object in the specification.
Authentication
Authentication is done using OAuth 2.0 https://tools.ietf.org/html/rfc6749 requesting an access token using either the client_credentials, password, or refresh_token grant types.
Scopes
We offer two OAuth scopes that can be used to restrict the scope of any API client’s operations.
The Brightbox IaaS API described here is covered by the infrastructure
scope.
Orbit is covered by the orbit
scope.
If a token is issued for orbit
it can not be used to access the infrastructure
API.
OAuth 2.0 Grant types
We currently allow accessing the API using client credentials (using API clients) or using a user’s own login credentials (using OAuth applications).
Before you can access the Brightbox API you need to have a client identifier and secret for the client you plan to use.
We support two types of client each linked to a different grant type.
Client Credentials using API clients
This is the simple Client Credentials (client_credentials
) grant type. API clients can only access the account that they belong to.
API client credentials are an identifier and secret issued to a single account to access the API, commonly used for authenticating automated systems.
To request an access token the Client must send a POST request to https://api.gb1.brightbox.com/token
The request must use Basic HTTP authentication using the client_id
as username and client_secret
as password.
It must include the following parameters:
Parameter | Description |
---|---|
grant_type | client_credentials |
Data can be sent with Content-Type of either application/x-www-form-urlencoded
or application/json
.
Example curl
request/response:
$ curl https://api.gb1.brightbox.com/token \
-X POST \
-u "cli-entid:secret" \
-d "grant_type=client_credentials"
{
"access_token": "414028a4b75139fc1b03b51dc294d1b4c591d666",
"token_type": "Bearer",
"scope": "infrastructure, orbit",
"expires_in": 7200
}
Example JSON request/response:
POST /token HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Basic Y2xpLWVudGlkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json
{"grant_type": "client_credentials"}
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Oauth-Scopes: infrastructure, orbit
Content-Length: 131
Date: Fri, 21 Aug 2015 11:05:48 GMT
Connection: Keep-Alive
{
"access_token": "1c2870d471741bc9c7a1a03ccf7485c2df4f443e",
"token_type": "Bearer",
"scope": "infrastructure, orbit",
"expires_in": 7200
}
See https://tools.ietf.org/html/rfc6749#section-4.4
Resource Owner Password Credentials using OAuth applications
This is OAuth 2‘s Resource Owner Password Credentials (password
) grant type. It is a bit harder to work with since it involves credentials for the client and also for the user.
We currently check that the client’s secret is correct which is optional in the OAuth 2.0 spec but all access rights comes from the user’s details.
Since a user can access several accounts, an additional account_id
parameter is required for most API calls to specify which is being used. This is not required for requesting a token.
In addition to the access token, users are returned a refresh token. This can be used to request a new access token without reentering your password.
To request an access token the Client must send a POST request to https://api.gb1.brightbox.com/token
The request must use Basic HTTP authentication using the client_id
as username and client_secret
as password.
It must include the following parameters:
Parameter | Description |
---|---|
grant_type | password |
username | User’s identifier or email. e.g usr-12345 , bob@example.com |
password | User’s password. e.g pa55w0rd! |
Data can be sent with Content-Type of either application/x-www-form-urlencoded
or application/json
.
Example curl
request/response:
$ curl https://api.gb1.brightbox.com/token \
-X POST \
-u "app-entid:secret" \
-d "grant_type=password" \
-d "username=bob@example.com" \
-d "password=bobKNOWSs3cUirty"
{
"access_token": "5a8fdabb155e1230dffd5a77a11d8885c74d862c",
"token_type": "Bearer",
"refresh_token": "6bbd76a3b2d87afe2b13e9bdfaae340e23b4ae26",
"scope": "infrastructure, orbit",
"expires_in": 7200
}
Example JSON request/response:
POST /token HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Basic Y2xpLWVudGlkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json
{"grant_type":"password"}
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Oauth-Scopes: infrastructure, orbit
Content-Length: 190
Date: Fri, 21 Aug 2015 11:02:41 GMT
Connection: Keep-Alive
{
"access_token": "0ace2df4de19d42ba7bcae392d0ece2ea6df49a6",
"token_type": "Bearer",
"refresh_token": "3f2a04d881c07edc6acc525b16b25de74d75debc",
"scope": "infrastructure, orbit",
"expires_in": 7200
}
See https://tools.ietf.org/html/rfc6749#section-4.3
Two Factor Authentication (2FA)
If you have enabled two factor authentication (2FA) you must also include the generated Time-based One Time Password (TOTP) with the token request.
You can do this in two ways. Preferably you can sent the TOTP using the X-BRIGHTBOX-OTP
header.
POST /token HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Basic Y2xpLWVudGlkOmNsaWVudF9zZWNyZXQ=
X-Brightbox-OTP: 123456
Content-Type: application/json
{"grant_type":"password"}
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Oauth-Scopes: infrastructure, orbit
Content-Length: 190
Date: Fri, 21 Aug 2015 11:02:41 GMT
Connection: Keep-Alive
{
"access_token": "0ace2df4de19d42ba7bcae392d0ece2ea6df49a6",
"token_type": "Bearer",
"refresh_token": "3f2a04d881c07edc6acc525b16b25de74d75debc",
"scope": "infrastructure, orbit",
"expires_in": 7200
}
Alternatively append the current TOTP to the password separated by a +
and send in place of your password. This may need to be URL encoded as %2B
depending on how the data is sent.
$ curl https://api.gb1.brightbox.com/token \
-X POST \
-u "app-entid:secret" \
-d "grant_type=password" \
-d "username=bob@example.com" \
-d "password=bobKNOWSs3cUirty%2B123456"
{
"access_token": "5a8fdabb155e1230dffd5a77a11d8885c74d862c",
"token_type": "Bearer",
"refresh_token": "6bbd76a3b2d87afe2b13e9bdfaae340e23b4ae26",
"scope": "infrastructure, orbit",
"expires_in": 7200
}
Refresh Token Credentials using OAuth applications
Refresh tokens are only granted to users authenticating with passwords. When an access token is given, a refresh token is also given.
You can request a new access token using a valid refresh token to extend access to the API without having to prompt for the password again.
The same client must be used to request an extension. Refresh tokens do expire but have a longer life than access_tokens.
To request an access token the Client must send a POST request to https://api.gb1.brightbox.com/token
The request must use Basic HTTP authentication using the client_id
as username and client_secret
as password.
It must include the following parameters:
Parameter | Description |
---|---|
grant_type | refresh_token |
refresh_token | Value of the token |
Data can be sent with Content-Type of either application/x-www-form-urlencoded
or application/json
.
Example curl
request/response:
$ curl https://api.gb1.brightbox.com/token \
-X POST \
-u "app-entid:secret" \
-d "grant_type=refresh_token" \
-d "refresh_token=3f2a04d881c07edc6acc525b16b25de74d75debc"
{
"access_token": "5a8fdabb155e1230dffd5a77a11d8885c74d862c",
"token_type": "Bearer",
"refresh_token": "6bbd76a3b2d87afe2b13e9bdfaae340e23b4ae26",
"scope": "infrastructure, orbit",
"expires_in": 7200
}
Example JSON request/response:
POST /token HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Basic Y2xpLWVudGlkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json
{"grant_type":"refresh_token","refresh_token":"6bbd76a3b2d87afe2b13e9bdfaae340e23b4ae26"}
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-Oauth-Scopes: infrastructure, orbit
Content-Length: 190
Date: Fri, 21 Aug 2015 11:02:41 GMT
Connection: Keep-Alive
{
"access_token": "0ace2df4de19d42ba7bcae392d0ece2ea6df49a6",
"token_type": "Bearer",
"refresh_token": "3f2a04d881c07edc6acc525b16b25de74d75debc",
"scope": "infrastructure, orbit",
"expires_in": 7200
}
See https://tools.ietf.org/html/rfc6749#section-6
Responses
A successful request returns a JSON response including:
access_token
the Bearer token used to access the APItoken_type
which is always "Bearer"refresh_token
for users using "password" which can be used to get replacement tokensscope
the scopes issued to this tokenexpires_in
the number of seconds the token is valid for (usually 7200 seconds.
Client applications should be designed to handle re-authentication on receipt of a 401 Unauthorised response from the API.
Unsuccessful requests return a 401 Unauthorised response if the credentials are wrong. For any other mistakes such as the wrong grant type it will return a 400 Bad Request.
Making API requests
Requests are made by including the access token in the HTTP Authorization header with the "Bearer" scheme. The token attribute must be set to the value returned from the token request.
The token is passed with any requests to the main API endpoint (api.gb1.brightbox.com) in the following form:
GET /1.0/servers HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Bearer k1bjflpsaj8wnrbrwzad0eqo36nxiha
See https://tools.ietf.org/html/rfc6749#section-5.1
If the token is valid for the requested resource the response body is return. If the token is invalid or expired the response will be a 401 Unauthorised HTTP response with details of the error.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error='token_expired'
See https://tools.ietf.org/html/rfc6749#section-5.2
Request format
To make a request of the API the Content-Type of the request must be in JSON. See http://www.json.org/
The format of is that of a JSON object with a name for each attribute or link a resource has.
The JSON specification does not require an Object’s names and values to be ordered. Unrecognised parameters being sent will be ignored.
Representation format
The responses you receive from the API will be represented in JSON.
Each resource can be represented in one of three ways.
Representation | Description |
---|---|
Full | This is a full view of the resource. All of the attributes are included and linked resources appear in the output as well |
Nested | This is a shorter representation that is used when this resource is beneath another full resource. A nested resource is secondary data to the main resource being accessed |
Collected | This is used when the resource is a member of a collection. It is shorter than the full response since many may be returned in one go |
The format of is that of a JSON object with a name for each attribute or link a resource has.
Only the first level of a linked resource is shown as well as a url to access that resource.
The type of representation that is returned by an API action is detailed in the summary of each action.
Exact details of the response contents are included in the resource’s documentation.
The JSON specification does not require an Object’s names and values to be ordered. You should not expect the responses to return in a particular order since that is not guaranteed.
Examples of each type of representation are given near the resource’s main documentation
Full representation
Full representations show as much information about a resource as is possible. This includes all attributes for the resource. It also includes the nested representations for any other resources that are linked to the requested resource.
This allows you to see a summary of related resources without too many additional API requests.
Nested representation
Nested representations are shorter summaries of a resource intended to appear beneath a main resource.
A nested resource is named using the relationship between the two resources.
When a resource is collected to a number of other resources, this collection is represented using the nested representations rather than a collection representation.
Collected representation
Collected representations are used when the resource is a member of a collection. Some details are omitted since several sets of results are expected to be returned and including full details would create very large responses.
A collection representation is wrapped in an Array in the returned JSON response. This allows iteration across the collection.
Data type formats
Data type | Format | Example | Description |
---|---|---|---|
AccountID | acc-3nsa9 | A Unique Identifier | |
ClientID | cli-dhjk2 | A Unique Identifier | |
CloudIpID | cip-2sjo9 | A Unique Identifier | |
CollaborationID | col-l4k9d | A Unique Identifier | |
DatabaseServerID | dbs-123ab | A Unique Identifier | |
DatabaseSnapshotID | dbs-123ab | A Unique Identifier | |
DatabaseTypeID | dbt-12345 | A Unique Identifier | |
FirewallPolicyID | fwp-ds423 | A Unique Identifier | |
FirewallRuleID | fwr-cmsd1 | A Unique Identifier | |
ImageID | img-fj23s | A Unique Identifier | |
InterfaceID | int-ds42k | A Unique Identifier | |
ServerID | srv-lv426 | A Unique Identifier | |
ServerGroupID | grp-sda44 | A Unique Identifier | |
ServerTypeID | typ-zx45f | A Unique Identifier | |
UserID | usr-kl435 | A Unique Identifier | |
ZoneID | zon-328ds | A Unique Identifier | |
DateTime | ISO8601 | 2010-07-23T11:39:14Z | This is a date and time represented as a string |
CountryCode | ISO 3166-1 two letter code | GB | ISO County code |
CountryName | ISO 3166-1 official name | United Kingdom | Country name |
RFC2822 | hello@brightbox.co.uk | A valid email address | |
VATNumber | GB916139623 | A Valid EU VAT number | |
Telephone | E.164 | +448456585545 | A Valid International telephone number in E.164 format prefixed with + |
Architecture | i686,x86_64 | i686 | OS architecture (32-bit or 64-bit) |
Healthcheck | Javascript Object | {"type": "http", "port": 80, "request": "/", "interval": 5000, "timeout": 5000, "threshold_up": 3, "threshold_down": 3} | Valid Healthcheck Object. Required attributes: type , port . All other attributes default to the values in the example |
Listener | Javascript Object | {"protocol": "http", "in": 80, "out": 8080, "timeout:50000", "proxy_protocol":null} | Valid Listener object. Timeout is optional and specified in miliseconds (default 50000). Valid protocols include tcp , http and https . proxy_protocol may be one of v1 , v2 , v2-ssl , v2-ssl-cn or null if unset. |
Port Translator | Javascript Object | {"protocol": "tcp", "incoming": 80, "outgoing": 8080} | Valid Port translator object. Valid protocols include tcp , udp . |
Node parameter | Javascript Object | {"node": "srv-3a97e"} | Node declaration passing an identifier as the node attribute. node is required. |
Password | String of at least 8 characters | +Tw9f&h3aP | The password should be between 8 and 72 characters long. |
BalancerPolicy | round-robin | The balancing policies available for a Load Balancer. This can currently be least-connections or round-robin . | |
ACME | Javascript Object | {"certificate": {"fingerprint": "351a35589946d9695f820fcb1491cd4b18aa1c6e5b45c8b00ca33d68ecbc256a", "issued_at": "2017-01-01T12:34:56Z", "expires_at": "2017-04-01T12:34:56Z" }, "domains": [{"identifier": "www.example.com", "status": "valid", "last_message": null}]} | A read only JSON representation of the ACME settings on a load balancer. |
SSLCertificate | Javascript Object | {"valid_from": "2016-01-01T12:34:56Z", "expires_at": "2017-12-31T23:59:59Z", "issuer": "/CN=CertsRUs Ltd", "subject": "/CN=example.com", "sslv3": false} . | JSON Object representing the SSL certificate uploaded to a load balancer |
Metadata service
The Brightbox cloud provides an EC2 compatible metadata service so that Servers are able to retrieve information about themselves while booting and whilst running. It is accessed via HTTP from the cloud server and uses IP-based authentication.
$ curl http://169.254.169.254/latest/meta-data
hostname
instance-id
instance-type
local-hostname
local-ipv4
placement/
public-ipv4
public-keys/
For example, to be able to retrieve the SSH public keys and add them to the authorized_keys
file. The public SSH key associated with the User’s profile is available via this metadata service.
$ curl http://169.254.169.254/latest/meta-data/public-keys/usr-kl34r/openssh-key
This is already setup on the Official Brightbox Ubuntu images so you only need to worry about this if you are using your own image.
Custom metadata can be also be attached to a Server using the user_data
attribute during creation. This data is treated as opaque and is stored and returned as application/octet-stream
.
See the AWS Developer Guide for details.
Resources
Account
Brightbox services are provided through an Account. A typical customer will have at least one Account through which they buy their Servers and other services. They may create multiple accounts if they wish e.g to manage servers for separate clients of theirs.
Accounts have limits on the resources that they can use. These are currently:
Viewing current usage is possible via the Account show action or via the management control panel.
States
State | Description |
pending | Account has been created but signup process is incomplete |
active | Account is active |
overdue | Account has overdue invoices |
warning | Account suspension is pending due to outstanding payments |
suspended | Account and services are suspended due to outstanding payments, billable account activity is prevented pending payment |
terminated | Account has been terminated due to terms and conditions violations e.g. non-payment |
closed | Account has been closed by the customer |
deleted | Account has been deleted from the system |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | AccountID | acc-3jd8s | true | true | Unique Identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/accounts/(account_id) | true | true | URL to access details of resource | |
name | string | String | Brightbox Systems Ltd. | true | true | ||
status | string | String | active | true | true | ||
address_1 | string | String | Leeds Media Centre | false | false | First line of address | |
address_2 | string | String | 21 Savile Mount | false | false | Second line of address | |
city | string | String | Leeds | false | false | ||
county | string | String | false | false | |||
postcode | string | String | LS7 3HZ | false | false | Postcode or Zipcode | |
country_code | string | CountryCode | GB | false | false | County code | |
country_name | string | CountryName | United Kingdom | false | false | Country name | |
vat_registration_number | string,null | VATNumber | GB916139623 | false | false | Valid EU VAT number (http://tinyurl.com/2fp4c2e) | |
telephone_number | string | Telephone | +448456585545 | false | false | Contact telephone number to speak to someone authorised to manage the account | |
telephone_verified | true,false | Boolean | false | false | false | Has the contact number been verified? If not Account may not be used to make certain requests | |
verified_telephone | string,null | E164 Telephone | +448456585545 | false | false | The actual number used to successfully verify the account | |
verified_at | string,null | DateTime | true | false | false | Has the contact number been verified? If not Account may not be used to make certain requests | |
verified_ip | string,null | IP Address | true | false | false | Has the contact number been verified? If not Account may not be used to make certain requests | |
valid_credit_card | boolean | Boolean | false | true | false | false | Has the Account's payment card been checked as valid? |
created_at | string | DateTime | (time of creation) | 2011-11-11T11:11:11Z | false | false | The date and time when the Account was created |
servers_used | number | Integer | 3 | false | true | The total number of Cloud servers currently in use | |
ram_limit | number | Integer | 20480 | false | true | The total RAM usage this Account is limited to in MB | |
ram_used | number | Integer | 2048 | false | true | The total RAM used by this Account in MB | |
dbs_instances_used | number | Integer | 4 | false | true | The total number of SQL instances currently in use | |
dbs_ram_limit | number | Integer | 8192 | false | true | The total RAM this account can use for database servers in MB | |
dbs_ram_used | number | Integer | 8192 | false | true | The total RAM this account is using for database servers in MB | |
cloud_ips_limit | number | Integer | 5 | false | true | The total number of Cloud IP addresses this Account is limited to | |
cloud_ips_used | number | Integer | 5 | false | true | The total number of Cloud IP addresses used by this Account | |
load_balancers_limit | number | Integer | 5 | false | true | The total number of Load Balancers this Account is limited to | |
load_balancers_used | number | Integer | 5 | false | true | The total number of Load Balancers used by this Account | |
library_ftp_host | string | String | ftp.library.gb1.brightbox.com | false | false | FTP host for uploading images to the cloud image library | |
library_ftp_user | string | String | (same as account ID) | acc-3jd8sh | false | false | FTP user for uploading images to the cloud image library |
library_ftp_password | string,null | String | (generated) | d25yd0dRArKSDQNS | false | false | FTP password for uploading images to the cloud image library (can be regenerated using the reset_ftp_password action) |
Links
Relationship | Resource | Description |
---|---|---|
owner | User | User with responsibility for the account |
users | User | Users connected to this account |
clients | ApiClient | API Clients connected to this account |
servers | Server | Servers connected to this account |
load_balancers | LoadBalancer | Load balancers connected to this account |
database_servers | DatabaseServers | Database servers connected to this account |
cloud_ips | CloudIpAddress | Cloud IPs assigned to this account |
server_groups | ServerGroup | Server groups connected to this account |
firewall_policies | FirewallPolicy | Firewall policies connected to this account |
images | Image | Images connected to this account |
zones | Zone | Zones used by this account |
Representations
Full Account representation example
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active",
"address_1": "Leeds Media Centre",
"address_2": "21 Savile Mount",
"city": "Leeds",
"county": "",
"postcode": "LS7 3HZ",
"country_code": "GB",
"country_name": "United Kingdom of Great Britain and Northern Ireland",
"vat_registration_number": "GB916139623",
"telephone_number": "+448456585545",
"telephone_verified": true,
"verified_telephone": "+448456585545",
"verified_at": "2011-10-01T00:01:00Z",
"verified_ip": "81.82.12.11",
"created_at": "2011-10-01T00:00:00Z",
"servers_used": 0,
"ram_limit": 32768,
"ram_used": 2048,
"cloud_ips_limit": 10,
"cloud_ips_used": 1,
"load_balancers_limit": 30,
"load_balancers_used": 1,
"dbs_instances_used": 0,
"dbs_ram_limit": 8192,
"dbs_ram_used": 0,
"valid_credit_card": true,
"library_ftp_host": "ftp.library.gb1.brightbox.com",
"library_ftp_user": "acc-43ks4",
"library_ftp_password": null,
"clients":
[{"id": "cli-dsse2",
"resource_type": "api_client",
"url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
"name": "dev client",
"description": "Development client from laptop",
"revoked_at": null,
"permissions_group": "full"}],
"images":
[],
"servers":
[],
"load_balancers":
[{"id": "lba-1235f",
"resource_type": "load_balancer",
"url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
"name": "",
"status": "creating",
"locked": false,
"buffer_size": 4096,
"https_redirect": false,
"created_at": "2011-10-01T01:00:00Z",
"deleted_at": null}],
"database_servers":
[],
"database_snapshots":
[],
"cloud_ips":
[{"id": "cip-k4a25",
"resource_type": "cloud_ip",
"url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
"status": "mapped",
"public_ip": "109.107.50.0",
"public_ipv4": "109.107.50.0",
"public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
"fqdn": "cip-k4a25.gb1.brightbox.com",
"reverse_dns": null,
"name": "product website ip"}],
"server_groups":
[{"id": "grp-sda44",
"resource_type": "server_group",
"url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
"name": "default",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"default": true,
"fqdn": "grp-sda44.gb1.brightbox.com"}],
"firewall_policies":
[{"id": "fwp-j3654",
"resource_type": "firewall_policy",
"url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
"default": true,
"name": "default",
"created_at": "2011-10-01T00:00:00Z",
"description": null}],
"owner":
{"id": "usr-kl435",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
"name": "John Jarvis",
"email_address": "jjarvis@example.com",
"2fa":
{"enabled": false}},
"users":
[{"id": "usr-kl435",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
"name": "John Jarvis",
"email_address": "jjarvis@example.com",
"2fa":
{"enabled": false}}],
"zones":
[{"id": "zon-328ds",
"resource_type": "zone",
"url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
"handle": "gb1"}]}
Collection Account representation example
[{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active",
"servers_used": 0,
"ram_limit": 32768,
"ram_used": 2048,
"dbs_instances_used": 0,
"dbs_ram_limit": 8192,
"dbs_ram_used": 0,
"cloud_ips_limit": 10,
"cloud_ips_used": 1,
"load_balancers_limit": 30,
"load_balancers_used": 1,
"clients":
[{"id": "cli-dsse2",
"resource_type": "api_client",
"url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
"name": "dev client",
"description": "Development client from laptop",
"revoked_at": null,
"permissions_group": "full"}],
"images":
[],
"servers":
[],
"load_balancers":
[{"id": "lba-1235f",
"resource_type": "load_balancer",
"url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
"name": "",
"status": "creating",
"locked": false,
"buffer_size": 4096,
"https_redirect": false,
"created_at": "2011-10-01T01:00:00Z",
"deleted_at": null}],
"database_servers":
[],
"database_snapshots":
[],
"cloud_ips":
[{"id": "cip-k4a25",
"resource_type": "cloud_ip",
"url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
"status": "mapped",
"public_ip": "109.107.50.0",
"public_ipv4": "109.107.50.0",
"public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
"fqdn": "cip-k4a25.gb1.brightbox.com",
"reverse_dns": null,
"name": "product website ip"}],
"server_groups":
[{"id": "grp-sda44",
"resource_type": "server_group",
"url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
"name": "default",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"default": true,
"fqdn": "grp-sda44.gb1.brightbox.com"}],
"firewall_policies":
[{"id": "fwp-j3654",
"resource_type": "firewall_policy",
"url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
"default": true,
"name": "default",
"created_at": "2011-10-01T00:00:00Z",
"description": null}],
"owner":
{"id": "usr-kl435",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
"name": "John Jarvis",
"email_address": "jjarvis@example.com",
"2fa":
{"enabled": false}},
"users":
[{"id": "usr-kl435",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
"name": "John Jarvis",
"email_address": "jjarvis@example.com",
"2fa":
{"enabled": false}}],
"zones":
[{"id": "zon-328ds",
"resource_type": "zone",
"url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
"handle": "gb1"}]}]
Nested Account representation example
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"}
Actions
List request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/accounts | Collection | 200 OK |
Parameters
This action does not have any parameters.
Get request
Get full details of the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/accounts/(account_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Update request
Update some details of the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/accounts/(account_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Brightbox Systems Ltd. |
|||
address_1 | String | First line of address | Leeds Media Centre |
||
address_2 | String | Second line of address | 21 Savile Mount |
||
city | String | Leeds |
|||
county | String | ||||
postcode | String | Postcode or Zipcode | LS7 3HZ |
||
country_code | CountryCode | GB |
|||
vat_registration_number | VATNumber | Must be a valid EU VAT number | GB916139623 |
||
telephone_number | Telephone | Contact telephone number to speak to someone authorised to manage the account | +448456585545 |
Reset ftp password request
Reset the image library ftp password for the account.
The response is the only time the new password is available in plaintext.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/accounts/(account_id)/reset_ftp_password | Member | 200 OK |
Parameters
This action does not have any parameters.
Api client
An application registered to an account in order to authenticate via OAuth2.0
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | ApiClient | cli-e690d | true | true | A unique identifier used to identify the client in requests | |
url | string | URL | https://api.gb1.brightbox.com/1.0/api_clients/(api_client_id) | true | true | URL to access details of resource | |
name | string | String | Reboot script | true | true | Human readable name | |
secret | string,null | String | (generated) | 79fdsjhkhk3 | false | false | An shared secret the client must present when authenticating |
description | string | String | CLI script to reboot servers programmatically | true | true | Verbose description of this client | |
permissions_group | string | String | full | full | true | true | Summary of the permissions granted to the client either full API access or limited to Orbit storage (full, storage) |
Links
Relationship | Resource | Description |
---|---|---|
account | Account | The account this client was created for and can access |
Representations
Full Api client representation example
{"id": "cli-dsse2",
"resource_type": "api_client",
"url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
"name": "dev client",
"description": "Development client from laptop",
"secret": null,
"revoked_at": null,
"permissions_group": "full",
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"}}
Collection Api client representation example
[{"id": "cli-dsse2",
"resource_type": "api_client",
"url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
"name": "dev client",
"description": "Development client from laptop",
"revoked_at": null,
"permissions_group": "full",
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"}}]
Nested Api client representation example
{"id": "cli-dsse2",
"resource_type": "api_client",
"url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
"name": "dev client",
"description": "Development client from laptop",
"revoked_at": null,
"permissions_group": "full"}
Actions
List request
Lists summary details of API clients owned by the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/api_clients | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Create request
Create a new API client for the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/api_clients | Member | 201 Created |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Reboot script |
|||
description | String | CLI script to reboot servers programmatically |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Get full details of the API client.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/api_clients/(api_client_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
Update some details of the API client.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/api_clients/(api_client_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Reboot script |
|||
description | String | CLI script to reboot servers programmatically |
|||
permissions_group | String | full |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
Destroy the API client.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/api_clients/(api_client_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Reset secret request
Resets the secret used by the API client to a new generated value.
The response is the only time the new secret is available in plaintext.
Already authenticated tokens will still continue to be valid until expiry.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/api_clients/(api_client_id)/reset_secret | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Cloud ip
A IPv4 publicly routed IP address that can be dynamically remapped.
States
State | Description |
unmapped | The CloudIP is not in use and available for mapping |
reserved | The Cloud IP has been reserved for a building server |
mapped | CloudIP is currently in use |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | CloudipID | cip-ja8ub | true | true | Unique identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/cloud_ips/(cloud_ip_id) | true | true | URL to access details of resource | |
name | string | Name | product website ip | true | true | Name assigned to the cloud IP | |
public_ip | string | IPAddress | (generated) | 109.107.42.129 | true | true | Old alias of IPv4 address |
public_ipv4 | string | IPAddress | (generated) | 109.107.42.129 | true | true | IPv4 address |
public_ipv6 | string | IPAddress | (generated) | 2a02:1348:ffff:ffff::6d6b:2a81 | true | true | IPv6 address |
fqdn | string | String | cip-12345.gb1.brightbox.com | true | true | Full qualified domain name | |
status | string | String | unmapped | mapped | true | true | Current state of the Cloud IP |
reverse_dns | string | Hostname | (generated) | cip-109-107-42-129.gb1.brightbox.com | true | true | The reverse DNS entry for the CloudIP |
port_translators | array | Array | [] | [{"incoming": 80, "outgoing": 8080, "protocol": "http"}, {"incoming": 81, "outgoing": 581, "protocol": "udp"] | false | true | Array of port translators |
Links
Relationship | Resource | Description |
---|---|---|
account | Account | Account this resource belongs to |
interface | Interface | The Interface that this CloudIP maps to, otherwise null |
server | Server | The Server to which the mapped Interface belongs to, otherwise null |
load_balancer | LoadBalancer | The LoadBalancer that this CloudIP maps to, otherwise null |
database_server | DatabaseServer | The LoadBalancer that this CloudIP maps to, otherwise null |
server_group | ServerGroup | A ServerGroup which the mapped the Cloud IP to each Interface in the group, otherwise null |
Representations
Full Cloud ip representation example
{"id": "cip-k4a25",
"resource_type": "cloud_ip",
"url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
"status": "mapped",
"public_ip": "109.107.50.0",
"public_ipv4": "109.107.50.0",
"public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
"fqdn": "cip-k4a25.gb1.brightbox.com",
"reverse_dns": null,
"port_translators":
[{"protocol": "http",
"incoming": 443,
"outgoing": 2443}],
"name": "product website ip",
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"interface":
{"id": "int-ds42k",
"resource_type": "interface",
"url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
"mac_address": "02:24:19:00:00:ee",
"ipv4_address": "81.15.16.17"},
"server":
{"id": "srv-lv426",
"resource_type": "server",
"url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
"name": "",
"status": "active",
"locked": false,
"hostname": "srv-lv426",
"fqdn": "srv-lv426.gb1.brightbox.com",
"created_at": "2011-10-01T01:00:00Z",
"started_at": "2011-10-01T01:01:00Z",
"deleted_at": null},
"load_balancer": null,
"server_group": null,
"database_server": null}
Collection Cloud ip representation example
[{"id": "cip-k4a25",
"resource_type": "cloud_ip",
"url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
"status": "mapped",
"public_ip": "109.107.50.0",
"public_ipv4": "109.107.50.0",
"public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
"fqdn": "cip-k4a25.gb1.brightbox.com",
"reverse_dns": null,
"port_translators":
[{"protocol": "http",
"incoming": 443,
"outgoing": 2443}],
"name": "product website ip",
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"interface":
{"id": "int-ds42k",
"resource_type": "interface",
"url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
"mac_address": "02:24:19:00:00:ee",
"ipv4_address": "81.15.16.17"},
"server":
{"id": "srv-lv426",
"resource_type": "server",
"url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
"name": "",
"status": "active",
"locked": false,
"hostname": "srv-lv426",
"fqdn": "srv-lv426.gb1.brightbox.com",
"created_at": "2011-10-01T01:00:00Z",
"started_at": "2011-10-01T01:01:00Z",
"deleted_at": null},
"load_balancer": null,
"server_group": null,
"database_server": null}]
Nested Cloud ip representation example
{"id": "cip-k4a25",
"resource_type": "cloud_ip",
"url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
"status": "mapped",
"public_ip": "109.107.50.0",
"public_ipv4": "109.107.50.0",
"public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
"fqdn": "cip-k4a25.gb1.brightbox.com",
"reverse_dns": null,
"name": "product website ip"}
Actions
List request
Lists summary details of cloud IP addresses owned by the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/cloud_ips | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Create request
Requests a new cloud IP address for the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/cloud_ips | Member | 201 Created |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
reverse_dns | Hostname | Reverse DNS hostname | cip-109-107-42-129.gb1.brightbox.com |
||
name | String | Name for Cloud IP | product website ip |
||
port_translators | Array | Port on which external clients connect and port on which your service is listening. | [{"protocol": "tcp", "incoming": 443, "outgoing": 2443}] |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Get full details of the cloud IP address.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/cloud_ips/(cloud_ip_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
Update some details of the cloud IP address.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/cloud_ips/(cloud_ip_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
reverse_dns | Hostname | Reverse DNS hostname | cip-109-107-42-129.gb1.brightbox.com |
||
name | String | Name for Cloud IP | product website ip |
||
port_translators | Array | Port on which external clients connect and port on which your service is listening. | [{"protocol": "tcp", "incoming": 443, "outgoing": 2443}] |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
Release the cloud IP address from the account’s ownership.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/cloud_ips/(cloud_ip_id) | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Map request
Maps (or points) a cloud IP address at a server’s interface, load balancer, SQL instance or server group to allow them to respond to public requests.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/cloud_ips/(cloud_ip_id)/map | No body | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | destination | DatabaseServerID|InterfaceID|LoadBalancerID|ServerGroupID | The ID of a resource to map the IP to (DatabaseServer, Interface, LoadBalancer or ServerGroup | int-abcde |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Unmap request
Unmaps a cloud IP address from its current destination making it available to remap. This remains in the account’s pool of addresses.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/cloud_ips/(cloud_ip_id)/unmap | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Collaboration
A collaboration forms the link between an Account and a User, giving the User access to the specified Account. As a collaboration is created, the User is invited to accept the collaboration via email. The collaboration can be accepted or rejected via the User Collaboration’s accept or reject methods. Once the collaboration is complete either party can end the collaboration. Account administrators can call delete on the Collaboration or the User can call delete on the User Collaboration.
States
State | Description |
pending | Collaboration was created and is awaiting acceptence/rejection from the User (via User Collaboration) |
accepted | Collaboration was accepted and is active |
rejected | Collaboration was rejected by the user |
cancelled | Collaboration was deleted before it entered the accepted state |
ended | Collaboration was accepted but has since been ended by either party |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | CollaborationID | col-klek3 | true | true | Unique ID for the collaboration | |
url | string | URL | https://api.gb1.brightbox.com/1.0/collaborations/(collaboration_id) | true | true | URL to access details of resource | |
string | user@example.net | true | true | ||||
role | string | String | admin | true | true | Simple and stable name of role | |
role_label | string | String | Account administrator | true | true | Verbose name of role | |
status | string | String | false | true | Current state of the collaboration | ||
created_at | string | Datetime | 2013-04-23T10:40:14Z | true | true | Time of Collaboration creation (UTC) | |
started_at | string | Datetime | 2013-05-23T10:40:14Z | true | true | Time of Collaboration start (UTC) | |
finished_at | string | Datetime | 2013-06-23T10:40:14Z | true | true | Time of Collaboration finish (UTC) |
Links
Relationship | Resource | Description |
---|---|---|
user | User | The User the Collaboration refers to |
account | Account | The Account the Collaboration refers to |
inviter | User | The User who created the Collaboration request |
Representations
Full Collaboration representation example
{"id": null,
"resource_type": "collaboration",
"url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
"status": "pending",
"email": "tclock@example.com",
"role": "admin",
"created_at": "2013-03-24T00:00:00Z",
"started_at": "2013-04-10T00:00:00Z",
"finished_at": "2013-05-10T00:00:00Z",
"role_label": "Collaborator",
"user": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"inviter":
{"id": "usr-kl435",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
"name": "John Jarvis",
"email_address": "jjarvis@example.com",
"2fa":
{"enabled": false}}}
Collection Collaboration representation example
[{"id": null,
"resource_type": "collaboration",
"url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
"status": "pending",
"email": "tclock@example.com",
"role": "admin",
"created_at": "2013-03-24T00:00:00Z",
"started_at": "2013-04-10T00:00:00Z",
"finished_at": "2013-05-10T00:00:00Z",
"role_label": "Collaborator",
"user": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"inviter":
{"id": "usr-kl435",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
"name": "John Jarvis",
"email_address": "jjarvis@example.com",
"2fa":
{"enabled": false}}}]
Nested Collaboration representation example
{"id": null,
"resource_type": "collaboration",
"url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
"status": "pending",
"email": "tclock@example.com",
"role": "admin",
"created_at": "2013-03-24T00:00:00Z",
"started_at": "2013-04-10T00:00:00Z",
"finished_at": "2013-05-10T00:00:00Z",
"role_label": "Collaborator"}
Actions
Create request
Invites the given email address to collaborate with the specified account. Existing users will be able to accept the collaboration whilst those without a Brightbox account will be invited to create one.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/collaborations | Member | 201 Created |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | String | Email address of user to invite | user@example.net |
||
Yes | role | String | Role to grant to the user. Currently only `admin` | admin |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
List request
Lists all the collaborations for the given account
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/collaborations | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Shows details of the collaboration
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/collaborations/(collaboration_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Resend request
Resends the invitation email to the collaborator
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/collaborations/(collaboration_id)/resend | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
Cancels or completes the collaboration
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/collaborations/(collaboration_id) | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Config map
A ConfigMap is a named collection of keys and values
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | ConfigMapID | cfg-42jkw | true | true | Unique identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/config_maps/(config_map_id) | true | true | URL to access details of resource | |
name | string | Name | product website ip | true | true | Name assigned to the ConfigMap | |
data | object | {"hostname":"tester", "ram":1024} | false | false | JSON object with keys/values making up the ConfigMap |
Representations
Full Config map representation example
{"id": null,
"resource_type": "config_map",
"url": "https://api.gb1.brightbox.com/1.0/config_maps/",
"name": "example.test",
"data":
{"setting": 45}}
Collection Config map representation example
[{"id": null,
"resource_type": "config_map",
"url": "https://api.gb1.brightbox.com/1.0/config_maps/",
"name": "example.test"}]
Nested Config map representation example
{"id": null,
"resource_type": "config_map",
"url": "https://api.gb1.brightbox.com/1.0/config_maps/",
"name": "example.test"}
Actions
List request
Lists all ConfigMaps
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/config_maps | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Create request
Create a new ConfigMap.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/config_maps | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Name for ConfigMap | product website ip |
||
Yes | data | Object | A JSON object set of keys/values for the ConfigMap. Max size is 1MiB of text. | {"hostname":"tester", "ram":1024} |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Get full details of the ConfigMap.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/config_maps/(config_map_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
Update some details of the ConfigMap.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/config_maps/(config_map_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Name for ConfigMap | product website ip |
||
data | Object | A JSON object set of keys/values to completely replace the ConfigMap with. Max size is 1MiB of text. | {"hostname":"tester", "ram":1024} |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
Delete the ConfigMap.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/config_maps/(config_map_id) | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Database server
States
State | Description |
creating | The DatabaseServer is being created |
active | The DatabaseServer is available for use |
deleting | The DatabaseServer is being deleted and is not available for use |
deleted | The DatabaseServer has been deleted and is not available for use |
failing | The DatabaseServer is being failed and is not available for use |
failed | The DatabaseServer has been failed and is not available for use |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | String | dbs-12345 | true | true | Unique Identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/database_servers/(database_server_id) | true | true | URL to access details of resource | |
name | string | String | My web server | true | true | Editable user label | |
description | string | String | Main user DB | true | true | Editable user label | |
status | string | String | active | true | true | ||
database_engine | string | String | mysql | mysql | true | true | The DBMS engine of the Database Server |
database_version | string | String | 5.5 | 5.5 | true | true | The version of the given engine in use |
admin_username | string,null | String | admin | false | false | Initial username required to login | |
admin_password | string,null | String | (generated) | k43;2kd432f | false | false | Initial password required to login, only available at creation or following a password reset request |
created_at | string | Datetime | 2010-07-23T10:40:14Z | true | true | Time of resource creation (UTC) | |
updated_at | string | Datetime | 2010-07-23T10:40:14Z | true | true | Time of resource creation (UTC) | |
deleted_at | string | Datetime | 2010-07-23T10:43:14Z | true | true | Time of resource creation (UTC) | |
allow_access | array | Array | [] | ['srv-12345', '192.168.1.1'] | true | true | An array of resources allowed to access the database. Accepted values include `any`, `IPv4 address`, `server identifier`, `server group identifier`. |
maintenance_weekday | integer | Integer | 0 | 3 | true | true | Numerical index of weekday (0 is Sunday, 1 is Monday...) to set when automatic updates may be performed |
maintenance_hour | integer | Integer | 6 | 3 | true | true | Number representing 24hr time start of maintenance window hour for x:00-x:59 (0-23) |
snapshots_schedule | string | String | (daily schedule with randomly selected hour [0-8]) | 0 5 * * * | false | false | A crontab pattern with to determine approximately when scheduled snapshots will run (must be at least hourly) |
snapshots_schedule_next_at | string | Datetime | 2010-07-23T05:00:00Z | false | false | ISO 8601 time in UTC when next approximate scheduled snapshot will be run | |
locked | true,false | Boolean | false | true | true | Is true if resource has been set as locked and can not be deleted |
Links
Relationship | Resource | Description |
---|---|---|
account | Account | The owning account |
database_type | DatabaseType | |
cloud_ips | CloudIps | |
zone | Zone | Zone this database server belongs to |
Representations
Full Database server representation example
{"id": "dbs-123ab",
"resource_type": "database_server",
"url": "https://api.gb1.brightbox.com/1.0/database_servers/dbs-123ab",
"name": "My Database Server",
"description": "Application one's DBS",
"admin_username": "admin",
"admin_password": null,
"allow_access":
[],
"database_engine": "mysql",
"database_version": "5.5",
"status": "active",
"locked": false,
"maintenance_weekday": 0,
"maintenance_hour": 6,
"snapshots_schedule": null,
"snapshots_schedule_next_at": null,
"created_at": "2011-10-01T01:00:00Z",
"updated_at": "2011-11-01T01:00:00Z",
"deleted_at": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"database_server_type":
{"id": "dbt-12345",
"resource_type": "database_type",
"url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
"name": "Small",
"description": "Database Type Small",
"disk_size": 81920,
"ram": 2048,
"default": false},
"cloud_ips":
[],
"zone":
{"id": "zon-328ds",
"resource_type": "zone",
"url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
"handle": "gb1"}}
Collection Database server representation example
[{"id": "dbs-123ab",
"resource_type": "database_server",
"url": "https://api.gb1.brightbox.com/1.0/database_servers/dbs-123ab",
"name": "My Database Server",
"description": "Application one's DBS",
"allow_access":
[],
"database_engine": "mysql",
"database_version": "5.5",
"status": "active",
"locked": false,
"maintenance_weekday": 0,
"maintenance_hour": 6,
"snapshots_schedule": null,
"snapshots_schedule_next_at": null,
"created_at": "2011-10-01T01:00:00Z",
"updated_at": "2011-11-01T01:00:00Z",
"deleted_at": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"database_server_type":
{"id": "dbt-12345",
"resource_type": "database_type",
"url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
"name": "Small",
"description": "Database Type Small",
"disk_size": 81920,
"ram": 2048,
"default": false},
"cloud_ips":
[],
"zone":
{"id": "zon-328ds",
"resource_type": "zone",
"url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
"handle": "gb1"}}]
Nested Database server representation example
{"id": "dbs-123ab",
"resource_type": "database_server",
"url": "https://api.gb1.brightbox.com/1.0/database_servers/dbs-123ab",
"name": "My Database Server",
"description": "Application one's DBS",
"allow_access":
[],
"database_engine": "mysql",
"database_version": "5.5",
"status": "active",
"locked": false,
"maintenance_weekday": 0,
"maintenance_hour": 6,
"created_at": "2011-10-01T01:00:00Z",
"updated_at": "2011-11-01T01:00:00Z",
"deleted_at": null}
Actions
List request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/database_servers | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Create request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/database_servers | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | My web server |
|||
description | String | Main user DB |
|||
database_type | String | dbt-12345 | dbt-12345 |
||
engine | String | mysql | Database engine to request | mysql |
|
version | String | 5.5 | Database version to request | 5.5 |
|
allow_access | Array | [] | Array of IP addresses to whitelist access from | ["192.168.1.2", "192.168.1.1"] |
|
maintenance_weekday | Integer | 0 | Numerical index of weekday (0 is Sunday, 1 is Monday...) to set when automatic updates may be performed | 0 |
|
maintenance_hour | Integer | 6 | Number representing 24hr time start of maintenance window hour for x:00-x:59 (0-23) | 6 |
|
snapshots_schedule | String | (daily schedule with randomly selected hour [0-8]) | Crontab pattern for scheduled snapshots. Must be at least hourly | 0 5 * * * |
|
snapshot | String | Identifier for an SQL snapshot to use as the basis of the new instance. Creates and restores the database from the snapshot. | dbi-12345 |
||
zone | String | (auto allocated unless set) | Brightbox zone to create SQL instance in | zon-12345 |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/database_servers/(database_server_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/database_servers/(database_server_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | My web server |
|||
description | String | Main user DB |
|||
allow_access | Array | ["192.168.1.2", "192.168.1.1"] | ... | ["192.168.1.2", "192.168.1.1"] |
|
maintenance_weekday | Integer | Numerical index of weekday (0 is Sunday, 1 is Monday...) to set when automatic updates may be performed | 3 |
||
maintenance_hour | Integer | Number representing 24hr time start of maintenance window hour for x:00-x:59 (0-23) | 12 |
||
snapshots_schedule | String | Crontab pattern for scheduled snapshots. Must be at least hourly | 0 5 * * * |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/database_servers/(database_server_id) | Member | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Snapshot request
Requests a snapshot of the database server to be made for restoring back to when it was made. The identifier of the new snapshot is returned by the response in a Link header
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/database_servers/(database_server_id)/snapshot | Member | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Reset password request
This requests the admin password for the database server is reset. The new admin_password
is only returned in the JSON response to this request.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/database_servers/(database_server_id)/reset_password | Member | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Lock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/database_servers/(database_server_id)/lock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Unlock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/database_servers/(database_server_id)/unlock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Database snapshot
States
State | Description |
creating | The snapshot is being taken and prepared for reuse |
available | The snapshot is available for use |
deleted | The snapshot details have been deleted |
failed | The snapshot failed to complete successfully |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | String | dbi-12345 | true | true | Unique Identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/database_snapshots/(database_snapshot_id) | true | true | URL to access details of resource | |
name | string | String | My web server | true | true | Editable user label | |
description | string | String | Main user DB | true | true | Editable user label | |
status | string | String | available | true | true | ||
database_engine | string | String | mysql | true | true | The engine of the database used to create this snapshot | |
database_version | string | String | 5.5 | true | true | The version of the database engine used to create this snapshot | |
size | number | Integer | 10485760 | true | true | Size of database partition in megabytes | |
created_at | string | Datetime | 2010-07-23T10:40:14Z | true | true | Time of resource creation (UTC) | |
updated_at | string | Datetime | 2010-07-23T10:40:14Z | true | true | Time of resource creation (UTC) | |
deleted_at | string | Datetime | 2010-07-23T10:43:14Z | true | true | Time of resource creation (UTC) | |
locked | true,false | Boolean | false | true | true | Is true if resource has been set as locked and can not be deleted |
Representations
Full Database snapshot representation example
{"id": "dbi-12345",
"resource_type": "database_snapshot",
"url": "https://api.gb1.brightbox.com/1.0/database_snapshots/dbi-12345",
"name": "Snapshot of dbs-123ab 1 Nov 01:00",
"description": "",
"status": "available",
"locked": false,
"database_engine": "mysql",
"database_version": "5.5",
"source": null,
"size": 0,
"created_at": "2011-10-01T01:00:00Z",
"updated_at": "2011-11-01T01:00:00Z",
"deleted_at": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"}}
Collection Database snapshot representation example
[{"id": "dbi-12345",
"resource_type": "database_snapshot",
"url": "https://api.gb1.brightbox.com/1.0/database_snapshots/dbi-12345",
"name": "Snapshot of dbs-123ab 1 Nov 01:00",
"description": "",
"status": "available",
"locked": false,
"database_engine": "mysql",
"database_version": "5.5",
"source": null,
"size": 0,
"created_at": "2011-10-01T01:00:00Z",
"updated_at": "2011-11-01T01:00:00Z",
"deleted_at": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"}}]
Nested Database snapshot representation example
{"id": "dbi-12345",
"resource_type": "database_snapshot",
"url": "https://api.gb1.brightbox.com/1.0/database_snapshots/dbi-12345",
"name": "Snapshot of dbs-123ab 1 Nov 01:00",
"description": "",
"status": "available",
"locked": false,
"database_engine": "mysql",
"database_version": "5.5",
"source": null,
"size": 0,
"created_at": "2011-10-01T01:00:00Z",
"updated_at": "2011-11-01T01:00:00Z",
"deleted_at": null}
Actions
List request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/database_snapshots | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/database_snapshots/(database_snapshot_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
Update some details of the server.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/database_snapshots/(database_snapshot_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Editable label | My web server |
||
description | String | Editable label | Main user DB |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/database_snapshots/(database_snapshot_id) | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Lock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/database_snapshots/(database_snapshot_id)/lock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Unlock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/database_snapshots/(database_snapshot_id)/unlock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Database type
All Database Servers are created with a type. The type represents the available RAM and Disk space of the Server.
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | String | dbt-abcde | true | true | Unique Identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/database_types/(database_type_id) | true | true | URL to access details of resource | |
name | string | String | Database Nano | true | true | The name of this Database Server type | |
description | string | String | Database Nano Server | true | true | The description of this Database Server type | |
ram | number | Integer | 2048 | true | true | RAM in megabytes | |
disk_size | number | Integer | 81920 | true | true | Disk size in megabytes | |
default | true,false | Boolean | true | true | true | Is this type the default offered? |
Representations
Full Database type representation example
{"id": "dbt-12345",
"resource_type": "database_type",
"url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
"name": "Small",
"description": "Database Type Small",
"disk_size": 81920,
"ram": 2048,
"default": false}
Collection Database type representation example
[{"id": "dbt-12345",
"resource_type": "database_type",
"url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
"name": "Small",
"description": "Database Type Small",
"disk_size": 81920,
"ram": 2048,
"default": false}]
Nested Database type representation example
{"id": "dbt-12345",
"resource_type": "database_type",
"url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
"name": "Small",
"description": "Database Type Small",
"disk_size": 81920,
"ram": 2048,
"default": false}
Actions
List request
List database server types.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/database_types | Collection | 200 OK |
Parameters
This action does not have any parameters.
Get request
Get details of the database server type.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/database_types/(database_type_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Firewall policy
A collection of Firewall Rules
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | FirewallPolicyID | fwp-r4532 | true | true | Unique identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/firewall_policies/(firewall_policy_id) | true | true | URL to access details of resource | |
default | true,false | Boolean | false | false | Is this the default for the account | ||
name | string,null | String | the_wall | false | false | An optional name of the policy | |
description | string,null | String | false | false | An optional description of the policy | ||
created_at | string | Datetime | 2010-07-23T10:40:14Z | true | true | Time of Firewall Policy creation (UTC) |
Links
Relationship | Resource | Description |
---|---|---|
account | Account | Account this policy belongs to |
server_group | ServerGroup | The server group using this policy |
rules | FirewallRule | Firewall rules that are included in this policy |
Representations
Full Firewall policy representation example
{"id": "fwp-j3654",
"resource_type": "firewall_policy",
"url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
"default": true,
"name": "default",
"created_at": "2011-10-01T00:00:00Z",
"description": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"server_group":
{"id": "grp-sda44",
"resource_type": "server_group",
"url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
"name": "default",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"default": true,
"fqdn": "grp-sda44.gb1.brightbox.com"},
"rules":
[{"id": "fwr-k32ls",
"resource_type": "firewall_rule",
"url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
"source": "srv-lv426",
"source_port": "80,443,21",
"destination": null,
"destination_port": null,
"protocol": "tcp",
"icmp_type_name": null,
"description": null,
"created_at": "2011-10-01T00:00:00Z"}]}
Collection Firewall policy representation example
[{"id": "fwp-j3654",
"resource_type": "firewall_policy",
"url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
"default": true,
"name": "default",
"created_at": "2011-10-01T00:00:00Z",
"description": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"server_group":
{"id": "grp-sda44",
"resource_type": "server_group",
"url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
"name": "default",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"default": true,
"fqdn": "grp-sda44.gb1.brightbox.com"},
"rules":
[{"id": "fwr-k32ls",
"resource_type": "firewall_rule",
"url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
"source": "srv-lv426",
"source_port": "80,443,21",
"destination": null,
"destination_port": null,
"protocol": "tcp",
"icmp_type_name": null,
"description": null,
"created_at": "2011-10-01T00:00:00Z"}]}]
Nested Firewall policy representation example
{"id": "fwp-j3654",
"resource_type": "firewall_policy",
"url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
"default": true,
"name": "default",
"created_at": "2011-10-01T00:00:00Z",
"description": null}
Actions
List request
Lists summary details of firewall policies
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/firewall_policies | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Create request
Create a new firewall policy for the account.
Optionally applying to a server group at creation time.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/firewall_policies | Member | 201 Created |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
server_group | ServerGroupID | ||||
name | String | Editable label | the_wall |
||
description | String | Longer editable description |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Get details of the firewall policy
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/firewall_policies/(firewall_policy_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
Updates details of the firewall policy
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/firewall_policies/(firewall_policy_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Editable label | the_wall |
||
description | String | Longer editable description |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Apply to request
Applies firewall policy to given server group
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/firewall_policies/(firewall_policy_id)/apply_to | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | server_group | ServerGroupID | Server Group to apply to |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Remove request
Removes firewall policy from given server group
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/firewall_policies/(firewall_policy_id)/remove | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | server_group | ServerGroupID | Server Group to remove |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
Destroy the firewall policy if not in use.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/firewall_policies/(firewall_policy_id) | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Firewall rule
A firewall rule representing a single ‘ACCEPT’ rule
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | FirewallRuleID | fwr-83208 | true | true | Unique identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/firewall_rules/(firewall_rule_id) | true | true | URL to access details of resource | |
source | string | String | false | false | Subnet, ServerGroup or ServerID. 'any','10.1.1.23/32' or 'srv-4ktk4' | ||
source_port | string | String | false | false | single port, multiple ports or range separated by '-' or ':'; upto 255 characters example - '80', '80,443,21' or '3000-3999' | ||
destination | string | String | false | false | Subnet, ServerGroup or ServerID. '10.1.1.23/32' or 'srv-4ktk4' | ||
destination_port | string | String | false | false | single port, multiple ports or range separated by '-' or ':'; upto 255 characters example '80', '80,443,21' or '3000-3999' | ||
protocol | string | String | tcp | false | false | Protocol Number or One of 'tcp', 'udp', 'icmp' | |
icmp_type_name | string | String | echo-request | false | false | ICMP type name. 'echo-request', 'echo-reply' | |
description | string,null | String | false | false | Arbitary string | ||
created_at | string | Datetime | 2010-07-23T10:40:14Z | true | true | Time of Firewall Rule creation (UTC) |
Links
Relationship | Resource | Description |
---|---|---|
firewall_policy | FirewallPolicy | The firewall policy this rule is linked to |
Representations
Full Firewall rule representation example
{"id": "fwr-k32ls",
"resource_type": "firewall_rule",
"url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
"source": "srv-lv426",
"source_port": "80,443,21",
"destination": null,
"destination_port": null,
"icmp_type_name": null,
"protocol": "tcp",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"firewall_policy":
{"id": "fwp-j3654",
"resource_type": "firewall_policy",
"url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
"default": true,
"name": "default",
"created_at": "2011-10-01T00:00:00Z",
"description": null}}
Collection Firewall rule representation example
[{"id": "fwr-k32ls",
"resource_type": "firewall_rule",
"url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
"source": "srv-lv426",
"source_port": "80,443,21",
"destination": null,
"destination_port": null,
"protocol": "tcp",
"icmp_type_name": null,
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"firewall_policy":
{"id": "fwp-j3654",
"resource_type": "firewall_policy",
"url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
"default": true,
"name": "default",
"created_at": "2011-10-01T00:00:00Z",
"description": null}}]
Nested Firewall rule representation example
{"id": "fwr-k32ls",
"resource_type": "firewall_rule",
"url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
"source": "srv-lv426",
"source_port": "80,443,21",
"destination": null,
"destination_port": null,
"protocol": "tcp",
"icmp_type_name": null,
"description": null,
"created_at": "2011-10-01T00:00:00Z"}
Actions
Create request
Create a new firewall rule for a firewall policy.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/firewall_rules | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | firewall_policy | FirewallPolicyID | |||
protocol | String | tcp |
|||
source | String | Required unless destination is set. | |||
source_port | String | ||||
destination | String | Required unless source is set | |||
destination_port | String | ||||
icmp_type_name | String | echo-request |
|||
description | String |
Get request
Get full details of the firewall rule.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/firewall_rules/(firewall_rule_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Update request
Update some settings of the firewall rule.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/firewall_rules/(firewall_rule_id) | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
protocol | String | tcp |
|||
source | String | Required unless destination is set. | |||
source_port | String | ||||
destination | String | Required unless source is set | |||
destination_port | String | ||||
icmp_type_name | String | echo-request |
|||
description | String |
Delete request
Destroy the firewall rule.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/firewall_rules/(firewall_rule_id) | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Image
An Image is virtual disk image used as the basis of the server.
States
State | Description |
creating | This Image is being created from a Server and is not yet complete |
available | This Image is available for selection |
deprecated | This Image is not listed but is available for new servers |
unavailable | This Image is no longer available for new servers |
deleting | This Image is being deleted and is no longer available for use |
deleted | This image has been deleted and is no longer available for use |
failed | This image failed to create and is unavailable for use |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | ImageID | img-9vxqi | true | true | Unique Identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/images/(image_id) | true | true | URL to access details of resource | |
name | string | String | Brightbox Lucid 32 | true | true | Editable label for this image | |
username | string | String | ubuntu | true | true | Username to use - when logging in to server booted with the image | |
status | string | String | available | true | true | The current state of the image | |
description | string | String | Jeremy's debian ec2 image | true | true | A description of the Image | |
source | string | String | jeremy_debian-32_ec2 | true | true | The source of this image (i.e the uploaded file or the server it was a snapshot of) | |
source_type | string | String | upload | true | true | The type of source for this image (i.e upload or snapshot) | |
arch | string | Architecture | x86_64 | true | true | OS architecture | |
created_at | string | Datetime | true | true | The time this image was created/registered (UTC) | ||
public | true,false | Boolean | true | true | true | Is this Image available to other customers? | |
official | true,false | Boolean | true | true | true | Is this Image an official Brightbox provided one | |
compatibility_mode | true,false | Boolean | true | false | true | Does this image require a non-virtio VM shell? | |
virtual_size | number | Integer | 1024 | false | true | The virtual size of the disk image "container" in MB | |
disk_size | number | Integer | 395 | false | true | The actual size of the data within this Image in MB | |
min_ram | number,null | Integer | 1024 | false | true | The minimum amount of RAM needed for this Image in MB. If unspecified is null | |
owner | string | AccountID | acc-bright | true | true | The account ID who created this account | |
licence_name | string | String | Windows 2008 Server | false | false | The Licence name of this image | |
locked | true,false | Boolean | false | true | true | Is true if resource has been set as locked and can not be deleted |
Links
Relationship | Resource | Description |
---|---|---|
ancestor | Image | This is the ancestor Image from which this Image was created |
Representations
Full Image representation example
{"id": "img-3ikco",
"resource_type": "image",
"url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
"name": "Ubuntu Lucid 10.04 server",
"status": "available",
"locked": false,
"username": "ubuntu",
"description": "Expands root partition automatically. login: ubuntu using stored ssh key",
"source": "ubuntu-lucid-daily-i64-server-20110509",
"arch": "x86_64",
"created_at": "2011-05-09T12:00:00Z",
"official": true,
"public": true,
"compatibility_mode": false,
"source_type": "upload",
"disk_size": 560,
"virtual_size": 1409,
"min_ram": null,
"owner": "acc-43ks4",
"licence_name": "Windows 2008",
"ancestor": null}
Collection Image representation example
[{"id": "img-3ikco",
"resource_type": "image",
"url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
"name": "Ubuntu Lucid 10.04 server",
"username": "ubuntu",
"status": "available",
"locked": false,
"description": "Expands root partition automatically. login: ubuntu using stored ssh key",
"source": "ubuntu-lucid-daily-i64-server-20110509",
"arch": "x86_64",
"created_at": "2011-05-09T12:00:00Z",
"owner": "acc-43ks4",
"official": true,
"public": true,
"compatibility_mode": false,
"source_type": "upload",
"disk_size": 560,
"virtual_size": 1409,
"min_ram": null,
"ancestor": null}]
Nested Image representation example
{"id": "img-3ikco",
"resource_type": "image",
"url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
"name": "Ubuntu Lucid 10.04 server",
"username": "ubuntu",
"status": "available",
"locked": false,
"description": "Expands root partition automatically. login: ubuntu using stored ssh key",
"source": "ubuntu-lucid-daily-i64-server-20110509",
"arch": "x86_64",
"created_at": "2011-05-09T12:00:00Z",
"official": true,
"public": true,
"owner": "acc-43ks4"}
Actions
List request
Lists summary details of images available for use by the Account. It includes those available to all customers
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/images | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Create request
Create a new image for the account by registering it against an image stored within the Brightbox cloud image library.
The disk image must be in place before you can attempt to create a reference in the API.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/images | Member | 201 Created |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | source | String | Filename of the image uploaded to /images within Orbit. Can consist of letters, numbers or '-_+.~^' | jeremy_debian-32_ec2 |
|
Yes | arch | Architecture | OS architecture this image is built for | x86_64 |
|
name | String | Name for this image. If no name is specified, a name will be autogenerated based on the source filename & current time. Can be modified later. | Brightbox Lucid 32 |
||
username | String | Username for the image | ubuntu |
||
public | Boolean | true |
|||
compatibility_mode | Boolean | true |
|||
description | String | Jeremy's debian ec2 image |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Get full details of the image.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/images/(image_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
Update some details of the image.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/images/(image_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Brightbox Lucid 32 |
|||
username | String | ||||
arch | String | x86_64 |
|||
status | String | One of the three user changable states: 'available', 'deprecated' or 'unavailable' | available |
||
public | Boolean | true |
|||
compatibility_mode | Boolean | true |
|||
description | String | Jeremy's debian ec2 image |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
Destroy the image.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/images/(image_id) | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Lock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/images/(image_id)/lock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Unlock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/images/(image_id)/unlock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Interface
An Interface resource represents the network interface of a Server. Each Server has one Interface, created automatically when the Server is created. An interface has an IPv4 ("local") address and, optionally, an IPv6 ("public") address.
Future versions of the API should support creation of multiple Interfaces per Server to enable, for example, multiple SSL applications per server.
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | InterfaceID | int-mc3a9 | true | true | Unique Identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/interfaces/(interface_id) | true | true | URL to access details of resource | |
mac_address | string | MAC Address | 02:24:19:6e:18:36 | true | true | The MAC address for this Interface | |
ipv4_address | string | IP Address | 10.110.24.54 | true | true | The IPv4 address for this Interface | |
ipv6_address | string | IPv6 Address | 2a02:1348:dead:0:0024:19ff:fe6e:1835 | true | true | The IPv6 address for this Interface |
Links
Relationship | Resource | Description |
---|---|---|
server | Server | The server this interface is connected to |
Representations
Full Interface representation example
{"id": "int-ds42k",
"resource_type": "interface",
"url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
"mac_address": "02:24:19:00:00:ee",
"ipv4_address": "81.15.16.17",
"server": null}
Collection Interface representation example
[{"id": "int-ds42k",
"resource_type": "interface",
"url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
"mac_address": "02:24:19:00:00:ee",
"ipv4_address": "81.15.16.17",
"server": null}]
Nested Interface representation example
{"id": "int-ds42k",
"resource_type": "interface",
"url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
"mac_address": "02:24:19:00:00:ee",
"ipv4_address": "81.15.16.17"}
Actions
Get request
Get full details of the interface.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/interfaces/(interface_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Load balancer
A load balancer balances requests between multiple servers
States
State | Description |
creating | The LoadBalancer is being created |
active | The LoadBalancer is available for use |
deleting | The LoadBalancer is being deleted and is not available for use |
deleted | The LoadBalancer has been deleted and is not available for use |
failing | The LoadBalancer is being failed and is not available for use |
failed | The LoadBalancer has been failed and is not available for use |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | LoadBalancerID | lba-dja0s | true | true | Unique identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/load_balancers/(load_balancer_id) | true | true | URL to access details of resource | |
name | string | String | My first loadbalancer | true | true | Editable user label | |
status | string | String | active | true | true | See states | |
listeners | array | Array | [{"in": 80, "out": 8080, "protocol": "http", "timeout": 50000}, {"in": 81, "out": 81, "protocol": "http+ws", "timeout": 10000}] | false | true | Array of Listener objects | |
policy | string | BalancerPolicy | least-connections | false | true | Method of load balancing. Supports `least-connections`, `round-robin` or `source-address`) | |
healthcheck | object | Healthcheck | {"type": "http", "request": "/", "port": 80, "interval": 5000, "timeout": 5000, "threshold_up": 3, "threshold_down": 3} | false | true | Healthcheck options | |
buffer_size | number | Integer | 4096 | true | true | Buffer size in bytes | |
https_redirect | true,false | Boolean | false | true | true | true | If a listener is available on port 443, when true this will redirect all HTTP traffic to HTTPS |
ssl_minimum_version | string | String | TLSv1.2 | TLSv1.2 | true | true | The minimum TLS/SSL version for the load balancer to accept. Supports `TLSv1.3`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3` and `SSLv3` |
acme | object | ACME | {"certificate": {"fingerprint": "351a35589946d9695f820fcb1491cd4b18aa1c6e5b45c8b00ca33d68ecbc256a", "issued_at": "2017-01-01T12:34:56Z", "expires_at": "2017-04-01T12:34:56Z" }, "domains": [{"identifier": "www.example.com", "status": "valid", "last_message": null}]} | false | false | Read only details for an Automatically managed certificate issued by Let's Encrypt | |
certificate | object | SSLCertificate | { "valid_from": "2016-01-01T12:34:56", "expires_at": "2017-12-31T23:59:59", "issuer": "/CN=CertsRUs Ltd", "subject": "/CN=example.com", "sslv3": false} | false | false | Details for a custom SSL certifcate uploaded to the load balancer (or null if none used) | |
created_at | string | DateTime | true | true | Time of LoadBalancer creation (UTC) | ||
deleted_at | string | DateTime | true | true | Time of LoadBalancer deletion (UTC) | ||
locked | true,false | Boolean | false | true | true | Is true if resource has been set as locked and can not be deleted |
Links
Relationship | Resource | Description |
---|---|---|
account | Account | Account this LoadBalancer belongs to |
nodes | Server | Servers connected to this LoadBalancer |
cloud_ips | CloudIp | Public Cloud IP addresses mapped to this server |
Representations
Full Load balancer representation example
{"id": "lba-1235f",
"resource_type": "load_balancer",
"url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
"name": "",
"status": "creating",
"locked": false,
"created_at": "2011-10-01T01:00:00Z",
"deleted_at": null,
"policy": "least-connections",
"buffer_size": 4096,
"https_redirect": false,
"listeners":
[{"protocol": "http",
"in": 80,
"out": 80,
"timeout": 50000,
"proxy_protocol": null}],
"healthcheck":
{"type": "http",
"request": "/",
"port": 80,
"interval": 5000,
"timeout": 5000,
"threshold_up": 3,
"threshold_down": 3},
"acme":
{"certificate": null,
"domains":
[]},
"ssl_minimum_version": "TLSv1.2",
"certificate": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"cloud_ips":
[],
"nodes":
[{"id": "srv-lv426",
"resource_type": "server",
"url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
"name": "",
"status": "active",
"locked": false,
"hostname": "srv-lv426",
"fqdn": "srv-lv426.gb1.brightbox.com",
"created_at": "2011-10-01T01:00:00Z",
"started_at": "2011-10-01T01:01:00Z",
"deleted_at": null}]}
Collection Load balancer representation example
[{"id": "lba-1235f",
"resource_type": "load_balancer",
"url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
"name": "",
"status": "creating",
"locked": false,
"created_at": "2011-10-01T01:00:00Z",
"deleted_at": null,
"policy": "least-connections",
"buffer_size": 4096,
"https_redirect": false,
"listeners":
[{"protocol": "http",
"in": 80,
"out": 80,
"timeout": 50000,
"proxy_protocol": null}],
"healthcheck":
{"type": "http",
"request": "/",
"port": 80,
"interval": 5000,
"timeout": 5000,
"threshold_up": 3,
"threshold_down": 3},
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"cloud_ips":
[],
"nodes":
[{"id": "srv-lv426",
"resource_type": "server",
"url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
"name": "",
"status": "active",
"locked": false,
"hostname": "srv-lv426",
"fqdn": "srv-lv426.gb1.brightbox.com",
"created_at": "2011-10-01T01:00:00Z",
"started_at": "2011-10-01T01:01:00Z",
"deleted_at": null}]}]
Nested Load balancer representation example
{"id": "lba-1235f",
"resource_type": "load_balancer",
"url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
"name": "",
"status": "creating",
"locked": false,
"buffer_size": 4096,
"https_redirect": false,
"created_at": "2011-10-01T01:00:00Z",
"deleted_at": null}
Actions
List request
Lists summary details of load balancers owned by the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/load_balancers | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Create request
Create a new load balancer for the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/load_balancers | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Editable label | My first loadbalancer |
||
nodes | Array | Array of Node parameters | [{"node": "srv-abcde"}] |
||
policy | String | least-connections | Method of Load balancing to use | least-connections |
|
domains | Array | Array of domain names to attempt to register with ACME | ["test.example.test"] |
||
certificate_pem | String | A X509 SSL certificate in PEM format. Must be included along with 'certificate_key'. If intermediate certificates are required they should be concatenated after the main certificate | |||
certificate_private_key | String | The RSA private key used to sign the certificate in PEM format. Must be included along with 'certificate_pem' | |||
ssl_minimum_version | String | The minimal TLS/SSL version to be supported. (TLSv1.3, TLSv1.2, TLSv1.1, TLSv1.0) (default: `TLSv1.2`) | TLSv1.2 |
||
sslv3 | Boolean | *Deprecated* This is no longer supported. | |||
Yes | listeners | Array | What port to listen on, port to pass through to and protocol (tcp, http, https) of listener. Timeout is optional and specified in milliseconds (default is 50000). | {"protocol": "http", "in": 80, "out": 80, "timeout": 50000} |
|
Yes | healthcheck | Healthcheck | Healthcheck options - only "port" and "type" required | {"type": "http", "port": 80} |
|
buffer_size | Integer | Buffer size in bytes | 2048 |
||
https_redirect | Boolean | If a listener is present on port 443, when true any requests to port 80 are redirected (default: false) | true |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Get full details of the load balancer.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/load_balancers/(load_balancer_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
Update some details of the load balancer.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/load_balancers/(load_balancer_id) | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Editable label | My first loadbalancer |
||
nodes | Array | Array of Node parameters | [{"node": "srv-abcde"}] |
||
policy | String | least-connections | Method of Load balancing to use | least-connections |
|
domains | Array | Array of domain names to attempt to register with ACME | ["test.example.test"] |
||
certificate_pem | String | A X509 SSL certificate in PEM format. Must be included along with 'certificate_key'. If intermediate certificates are required they should be concatenated after the main certificate | |||
certificate_private_key | String | The RSA private key used to sign the certificate in PEM format. Must be included along with 'certificate_pem' | |||
ssl_minimum_version | String | The minimal TLS/SSL version to be supported. (TLSv1.3, TLSv1.2, TLSv1.1, TLSv1.0) (default: `TLSv1.2`) | TLSv1.2 |
||
sslv3 | Boolean | *Deprecated* This is no longer supported. | |||
listeners | Array | What port to listen on, port to pass through to and protocol (tcp, http, https, http+ws, https+wss) of listener. Timeout is optional and specified in milliseconds (default is 50000). | {"protocol": "http", "in": 80, "out": 80, "timeout": 50000} |
||
healthcheck | Healthcheck | Healthcheck options - only "port" and "type" required | {"type": "http", "port": 80} |
||
buffer_size | Integer | Buffer size in bytes | 2048 |
||
https_redirect | Boolean | If a listener is present on port 443, when true any requests to port 80 are redirected (default: false) | true |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Add nodes request
Add a number of nodes to the load balancer
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/load_balancers/(load_balancer_id)/add_nodes | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | nodes | Array | Array of Node parameters | [{"node": "srv-abcde"}] |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Remove nodes request
Remove a number of nodes from the load balancer
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/load_balancers/(load_balancer_id)/remove_nodes | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | nodes | Array | Array of Node parameters | [{"node": "srv-abcde"}] |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Add listeners request
Adds a number of listeners to the load balancer to enable balancing across nodes for those settings.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/load_balancers/(load_balancer_id)/add_listeners | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | listeners | Array | Array of Listener parameters. Timeout is optional and specified in milliseconds. | {"protocol": "http", "in": 80, "out": 80, "timeout": 10000} |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Remove listeners request
Removes a number of listeners from a load balancer to cease balancing across nodes for those settings.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/load_balancers/(load_balancer_id)/remove_listeners | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | listeners | Array | Array of Listener parameters | {"protocol": "http", "in": 80, "out": 80} |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
Destroy the LoadBalancer
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/load_balancers/(load_balancer_id) | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Lock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/load_balancers/(load_balancer_id)/lock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Unlock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/load_balancers/(load_balancer_id)/unlock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Server
A Server is a single cloud virtual machine running an operating system defined by the Image used to create it. There are several specifications of servers (Server Types) available.
The only required argument (at this time) is the Image you would like to use for the server. All other values will use a default value.
States
State | Description |
creating | Server is being prepared for use |
active | Server is available |
inactive | Server is shutdown |
deleting | Server is currently being deleted |
deleted | Server has been decommissioned |
failed | Server has failed and is no longer available |
unavailable | Server is currently unavailable |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | ServerID | srv-3a97e | true | true | Unique Identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/servers/(server_id) | true | true | URL to access details of resource | |
name | string | String | My web server | true | true | Editable user label | |
status | string | active | true | true | See states | ||
hostname | string | String | srv-3a97e | true | true | hostname | |
fqdn | string | String | srv-3a97e.gb1.brightbox.com | true | true | Full qualified domain name | |
created_at | string | Datetime | 2010-07-23T10:40:14Z | true | true | Time of server creation (UTC) | |
deleted_at | string,null | Datetime | 2010-07-23T10:41:00Z | true | true | Time server was deleted | |
started_at | string,null | Datetime | 2010-07-23T10:45:16Z | true | true | Time server was last started | |
user_data | string,null | Base64 | false | false | User definable data for use by the metadata service (must be Base64 encoded before submitting to API) | ||
compatibility_mode | true,false | Boolean | true | false | true | Does the server/image require a non-Virtio VM shell? Value is initially set from the requested image. It may be updated later but not at creation. | |
console_url | string,null | String | false | false | If active, URL that console page is available | ||
console_token | string,null | String | jlk4klj2 | false | false | One-time session password for console page on. Null unless part of an activate_console call | |
console_token_expires | string,null | Datetime | 2010-07-23T10:45:16Z | false | false | Time that latest active console session is valid until | |
disk_encrypted | true,false | Boolean | false | false | Was the server created with encryption at rest | ||
locked | true,false | Boolean | false | true | true | Is true if resource has been set as locked and can not be deleted |
Links
Relationship | Resource | Description |
---|---|---|
account | Account | Account this server belongs to |
image | Image | The Image used to create the server |
server_type | ServerType | The ServerType of server |
zone | Zone | The Zone where the server is located |
snapshots | Image | Images created by snapshotting this server |
cloud_ips | CloudIp | Public Cloud IP addresses mapped to this server |
interfaces | Interface | Network interfaces connected to this server |
server_groups | ServerGroup | Server groups this server belongs to |
Representations
Full Server representation example
{"id": "srv-lv426",
"resource_type": "server",
"url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
"name": "",
"status": "active",
"locked": false,
"hostname": "srv-lv426",
"created_at": "2011-10-01T01:00:00Z",
"started_at": "2011-10-01T01:01:00Z",
"deleted_at": null,
"user_data": null,
"fqdn": "srv-lv426.gb1.brightbox.com",
"compatibility_mode": false,
"console_url": null,
"console_token": null,
"console_token_expires": null,
"disk_encrypted": false,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"image":
{"id": "img-3ikco",
"resource_type": "image",
"url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
"name": "Ubuntu Lucid 10.04 server",
"username": "ubuntu",
"status": "available",
"locked": false,
"description": "Expands root partition automatically. login: ubuntu using stored ssh key",
"source": "ubuntu-lucid-daily-i64-server-20110509",
"arch": "x86_64",
"created_at": "2011-05-09T12:00:00Z",
"official": true,
"public": true,
"owner": "acc-43ks4"},
"server_type":
{"id": "typ-zx45f",
"resource_type": "server_type",
"url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
"name": "Small",
"status": "available",
"cores": 2,
"ram": 2048,
"disk_size": 81920,
"handle": "small"},
"zone":
{"id": "zon-328ds",
"resource_type": "zone",
"url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
"handle": "gb1"},
"cloud_ips":
[{"id": "cip-k4a25",
"resource_type": "cloud_ip",
"url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
"status": "mapped",
"public_ip": "109.107.50.0",
"public_ipv4": "109.107.50.0",
"public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
"fqdn": "cip-k4a25.gb1.brightbox.com",
"reverse_dns": null,
"name": "product website ip"}],
"interfaces":
[{"id": "int-ds42k",
"resource_type": "interface",
"url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
"mac_address": "02:24:19:00:00:ee",
"ipv4_address": "81.15.16.17"}],
"snapshots":
[],
"server_groups":
[{"id": "grp-sda44",
"resource_type": "server_group",
"url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
"name": "default",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"default": true,
"fqdn": "grp-sda44.gb1.brightbox.com"}]}
Collection Server representation example
[{"id": "srv-lv426",
"resource_type": "server",
"url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
"name": "",
"status": "active",
"locked": false,
"hostname": "srv-lv426",
"fqdn": "srv-lv426.gb1.brightbox.com",
"compatibility_mode": false,
"created_at": "2011-10-01T01:00:00Z",
"started_at": "2011-10-01T01:01:00Z",
"deleted_at": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"image":
{"id": "img-3ikco",
"resource_type": "image",
"url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
"name": "Ubuntu Lucid 10.04 server",
"username": "ubuntu",
"status": "available",
"locked": false,
"description": "Expands root partition automatically. login: ubuntu using stored ssh key",
"source": "ubuntu-lucid-daily-i64-server-20110509",
"arch": "x86_64",
"created_at": "2011-05-09T12:00:00Z",
"official": true,
"public": true,
"owner": "acc-43ks4"},
"server_type":
{"id": "typ-zx45f",
"resource_type": "server_type",
"url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
"name": "Small",
"status": "available",
"cores": 2,
"ram": 2048,
"disk_size": 81920,
"handle": "small"},
"zone":
{"id": "zon-328ds",
"resource_type": "zone",
"url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
"handle": "gb1"},
"cloud_ips":
[{"id": "cip-k4a25",
"resource_type": "cloud_ip",
"url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
"status": "mapped",
"public_ip": "109.107.50.0",
"public_ipv4": "109.107.50.0",
"public_ipv6": "2a02:1348:ffff:ffff::6d6b:3200",
"fqdn": "cip-k4a25.gb1.brightbox.com",
"reverse_dns": null,
"name": "product website ip"}],
"interfaces":
[{"id": "int-ds42k",
"resource_type": "interface",
"url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
"mac_address": "02:24:19:00:00:ee",
"ipv4_address": "81.15.16.17"}],
"snapshots":
[],
"server_groups":
[{"id": "grp-sda44",
"resource_type": "server_group",
"url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
"name": "default",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"default": true,
"fqdn": "grp-sda44.gb1.brightbox.com"}]}]
Nested Server representation example
{"id": "srv-lv426",
"resource_type": "server",
"url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
"name": "",
"status": "active",
"locked": false,
"hostname": "srv-lv426",
"fqdn": "srv-lv426.gb1.brightbox.com",
"created_at": "2011-10-01T01:00:00Z",
"started_at": "2011-10-01T01:01:00Z",
"deleted_at": null}
Actions
List request
Lists summary details of servers owned by the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/servers | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Create request
Create a new server for the account based on the required disk image.
Optionally can setup the type of server, zone to locate it, groups to join and custom metadata.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/servers | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | image | ImageID | The disk image to create the server from | img-da92s |
|
name | String | Editable label | My web server |
||
server_type | ServerTypeID | (current service default) | The hardware specification for the new server based on a Server Type | typ-k4js9 |
|
zone | ZoneID | (randomly allocated) | Zone in which to create new Server | zon-23j87 |
|
user_data | Base64 | Base64 encoded data made available to Cloud Init | |||
server_groups | Array | Array of server groups to add server to | ["grp-abcde"] |
||
cloud_ip | true or String | A Cloud IP that should be mapped as soon as the server is built. Either `true` to allocate a new Cloud IP or the identifier of an unmapped Cloud IP to reserve | cip-2kls3 |
||
disk_encrypted | Boolean | false | Should encryption at rest be enabled for this server? Automatically uses LUKS to encrypt the volume. | false |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Get full details of the server.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/servers/(server_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
Update some details of the server.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/servers/(server_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Editable label | My web server |
||
user_data | Base64 | User defined metadata | |||
server_groups | Array | Array of server groups to update server to being a member of. This replaces any existing groups | ["grp-abcde"] |
||
compatibility_mode | Boolean | Server needs to be shutdown and restarted for changes to this to take effect | true |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
Destroy the server and free up the resources.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/servers/(server_id) | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Start request
Will issue a start request for the server to become active.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/servers/(server_id)/start | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Stop request
Will issue a stop request for the server to become inactive.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/servers/(server_id)/stop | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Reboot request
Issues a ‘soft’ reboot to the server however the OS may ignore it. The console remains connected.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/servers/(server_id)/reboot | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Reset request
Issues a ‘hard’ reboot request to the server which can not be ignored by the OS. The console remains connected.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/servers/(server_id)/reset | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Shutdown request
Will issue a safe shutdown request for the server.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/servers/(server_id)/shutdown | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Activate console request
Enable console access via VNC to the server for 15 minutes.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/servers/(server_id)/activate_console | Member | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Snapshot request
Will issue a request to snapshot the Server
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/servers/(server_id)/snapshot | No body | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Lock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/servers/(server_id)/lock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Unlock resource request
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/servers/(server_id)/unlock_resource | No body | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Server group
A grouping of Servers
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | ServerGroupID | grp-kl43d | true | true | Unique identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/server_groups/(server_group_id) | true | true | URL to access details of resource | |
name | string,null | String | Web servers | true | true | Editable user label | |
created_at | string | Datetime | 2010-07-23T10:40:14Z | true | true | Time of Server Group creation (UTC) | |
description | string,null | String | Web servers for the main website app | true | true | Editable user description | |
default | true,false | Boolean | false | false | Is this the default for the account | ||
fqdn | string | String | grp-12345.gb1.brightbox.com | true | true | Full qualified domain name |
Links
Relationship | Resource | Description |
---|---|---|
account | Account | Account this server group belongs to |
firewall_policy | FirewallPolicy | Firewall policy linked to this group |
servers | Server | Servers that are members of this group |
Representations
Full Server group representation example
{"id": "grp-sda44",
"resource_type": "server_group",
"url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
"name": "default",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"default": true,
"fqdn": "grp-sda44.gb1.brightbox.com",
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"firewall_policy":
{"id": "fwp-j3654",
"resource_type": "firewall_policy",
"url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
"default": true,
"name": "default",
"created_at": "2011-10-01T00:00:00Z",
"description": null},
"servers":
[{"id": "srv-lv426",
"resource_type": "server",
"url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
"name": "",
"status": "active",
"locked": false,
"hostname": "srv-lv426",
"fqdn": "srv-lv426.gb1.brightbox.com",
"created_at": "2011-10-01T01:00:00Z",
"started_at": "2011-10-01T01:01:00Z",
"deleted_at": null}]}
Collection Server group representation example
[{"id": "grp-sda44",
"resource_type": "server_group",
"url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
"name": "default",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"default": true,
"fqdn": "grp-sda44.gb1.brightbox.com",
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"firewall_policy":
{"id": "fwp-j3654",
"resource_type": "firewall_policy",
"url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
"default": true,
"name": "default",
"created_at": "2011-10-01T00:00:00Z",
"description": null},
"servers":
[{"id": "srv-lv426",
"resource_type": "server",
"url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
"name": "",
"status": "active",
"locked": false,
"hostname": "srv-lv426",
"fqdn": "srv-lv426.gb1.brightbox.com",
"created_at": "2011-10-01T01:00:00Z",
"started_at": "2011-10-01T01:01:00Z",
"deleted_at": null}]}]
Nested Server group representation example
{"id": "grp-sda44",
"resource_type": "server_group",
"url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
"name": "default",
"description": null,
"created_at": "2011-10-01T00:00:00Z",
"default": true,
"fqdn": "grp-sda44.gb1.brightbox.com"}
Actions
List request
Lists summary details of server groups owned by the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/server_groups | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Create request
Create a new server group for the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/server_groups | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Editable user label | Web servers |
||
description | String | Editable user description | Web servers for the main website app |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Get details of the server group.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/server_groups/(server_group_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Update request
Update some details of the server group.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/server_groups/(server_group_id) | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Editable user label | Web servers |
||
description | String | Editable user description | Web servers for the main website app |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Add servers request
Add a number of servers to the server group.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/server_groups/(server_group_id)/add_servers | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | servers | Array | Array of Hashes containing {"server" => server_id} for each server to add | [{"server": "srv-abcd"}, {"server": "srv-12345"}] |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Remove servers request
Remove a number of servers from the server group.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/server_groups/(server_group_id)/remove_servers | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | servers | Array | Array of Server parameters to remove | [{"server": "srv-abcd"}, {"server": "srv-12345"}] |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Move servers request
Removes a number of server from the server group and adds them to another server group given in parameters.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/server_groups/(server_group_id)/move_servers | Member | 202 Accepted |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
Yes | servers | Array | Array of Hashes containing {"server" => server_id} for each server to remove | [{"server": "srv-abcd"}, {"server": "srv-12345"}] |
|
Yes | destination | server_group | ServerGroup to move servers to | grp-abcde |
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Delete request
Destroy the server group if not in use.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/server_groups/(server_group_id) | Member | 202 Accepted |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Server type
ServerType represents what we might currently call a product. All servers are created with a server type, which describes it’s configuration.
States
State | Description |
experimental | This server type is not yet available |
available | This server type is available for selection |
deprecated | This configuration is no longer available for new servers |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | ServerTypeID | typ-a97e6 | true | true | Unique Identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/server_types/(server_type_id) | true | true | URL to access details of resource | |
handle | string,null | String | nano | true | true | Unique (but editable) handle for this ServerType | |
name | string | String | Brightbox Nano | true | true | The name of this ServerType | |
status | string | String | true | true | The state of the ServerType | ||
cores | number | Integer | 2 | true | true | Number of CPU cores | |
ram | number | Integer | 2048 | true | true | RAM in megabytes | |
disk_size | number | Integer | true | true | Disk size in megabytes |
Representations
Full Server type representation example
{"id": "typ-zx45f",
"resource_type": "server_type",
"url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
"name": "Small",
"status": "available",
"cores": 2,
"ram": 2048,
"disk_size": 81920,
"handle": "small"}
Collection Server type representation example
[{"id": "typ-zx45f",
"resource_type": "server_type",
"url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
"name": "Small",
"status": "available",
"cores": 2,
"ram": 2048,
"disk_size": 81920,
"handle": "small"}]
Nested Server type representation example
{"id": "typ-zx45f",
"resource_type": "server_type",
"url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
"name": "Small",
"status": "available",
"cores": 2,
"ram": 2048,
"disk_size": 81920,
"handle": "small"}
Actions
List request
Lists summary details of server types available to the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/server_types | Collection | 200 OK |
Parameters
This action does not have any parameters.
Get request
Get full details of the server type.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/server_types/(server_type_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
User
Customers interact with Brightbox by creating a User (also known as "registering") on the Brightbox system and then logging in using their credentials (email,password). A user may have access to many Accounts, whether as the Owner or with limited permissions.
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | UserID | usr-e690d | true | true | Unique ID for user | |
url | string | URL | https://api.gb1.brightbox.com/1.0/users/(user_id) | true | true | URL to access details of resource | |
name | string | String | true | true | |||
email_address | string | user@example.net | true | true | |||
email_verified | true,false | Boolean | false | true | |||
ssh_key | string,null | String | false | false | This User's SSH public key (is available to meta-data service to enable scripted configuration) | ||
messaging_pref | true,false | Boolean | false | false | Receive marketing communications | ||
created_at | string | DateTime | (time of creation) | 2011-11-11T11:11:11Z | false | false | The date and time when the User was created |
Links
Relationship | Resource | Description |
---|---|---|
accounts | Account | Accounts the user has access to |
default_account | Account | Account the user first sees when logging in |
Representations
Full User representation example
{"id": "usr-kl435",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
"name": "John Jarvis",
"email_address": "jjarvis@example.com",
"email_verified": true,
"ssh_key": "",
"messaging_pref": true,
"created_at": null,
"2fa":
{"enabled": false},
"default_account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"accounts":
[{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"}]}
Collection User representation example
[{"id": "usr-kl435",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
"name": "John Jarvis",
"email_address": "jjarvis@example.com",
"email_verified": true,
"2fa":
{"enabled": false},
"default_account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"accounts":
[{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"}]}]
Nested User representation example
{"id": "usr-kl435",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
"name": "John Jarvis",
"email_address": "jjarvis@example.com",
"2fa":
{"enabled": false}}
Actions
List request
Lists summary details of user.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/users | Collection | 200 OK |
Parameters
This action does not have any parameters.
Get request
Get full details of the user.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/users/(user_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Update request
Update some details of your user profile.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
PUT | /1.0/users/(user_id) | Member | 200 OK |
Parameters
Required | Name | Type | Default | Description | Example |
---|---|---|---|---|---|
name | String | Jason Null | Jason Null |
||
email_address | jason@null.test | jason@null.test |
|||
ssh_key | String | ||||
password | Password | A password string that conforms to the minimum requirements | |||
password_confirmation | Password | A password string that conforms to the minimum requirements |
User collaboration
A collaboration forms the link between an Account and a User, giving the User access to the specified Account. User collaborations allow you to list and interact with Collaborations that the specified user has.
States
State | Description |
pending | Collaboration was created and is awaiting acceptence/rejection from the User (via User Collaboration) |
accepted | Collaboration was accepted and is active |
rejected | Collaboration was rejected by the user |
cancelled | Collaboration was deleted before it entered the accepted state |
ended | Collaboration was accepted but has since been ended by either party |
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | CollaborationID | col-klek3 | true | true | Unique ID for the collaboration | |
url | string | URL | https://api.gb1.brightbox.com/1.0/user/collaborations/(user_collaboration_id) | true | true | URL to access details of resource | |
string | user@example.net | true | true | ||||
role | string | String | admin | true | true | Simple and stable name of role | |
role_label | string | String | Account administrator | true | true | Verbose name of role | |
status | string | String | false | true | Current state of the collaboration | ||
created_at | string | Datetime | 2013-04-23T10:40:14Z | true | true | Time of Collaboration creation (UTC) | |
started_at | string | Datetime | 2013-05-23T10:40:14Z | true | true | Time of Collaboration start (UTC) | |
finished_at | string | Datetime | 2013-06-23T10:40:14Z | true | true | Time of Collaboration finish (UTC) |
Links
Relationship | Resource | Description |
---|---|---|
user | User | The User the Collaboration refers to |
account | Account | The Account the Collaboration refers to |
inviter | User | The User who created the Collaboration request |
Representations
Full User collaboration representation example
{"id": null,
"resource_type": "collaboration",
"url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
"status": "pending",
"email": "jjarvis@example.com",
"role": "admin",
"created_at": null,
"started_at": null,
"finished_at": null,
"role_label": "Collaborator",
"user": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"inviter":
{"id": "usr-e8t4w",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-e8t4w",
"name": "Tom Clock",
"email_address": "tclock@example.com",
"2fa":
{"enabled": false}}}
Collection User collaboration representation example
[{"id": null,
"resource_type": "collaboration",
"url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
"status": "pending",
"email": "jjarvis@example.com",
"role": "admin",
"created_at": null,
"started_at": null,
"finished_at": null,
"role_label": "Collaborator",
"user": null,
"account":
{"id": "acc-43ks4",
"resource_type": "account",
"url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
"name": "Brightbox",
"status": "active"},
"inviter":
{"id": "usr-e8t4w",
"resource_type": "user",
"url": "https://api.gb1.brightbox.com/1.0/users/usr-e8t4w",
"name": "Tom Clock",
"email_address": "tclock@example.com",
"2fa":
{"enabled": false}}}]
Nested User collaboration representation example
{"id": null,
"resource_type": "collaboration",
"url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
"status": "pending",
"email": "jjarvis@example.com",
"role": "admin",
"created_at": null,
"started_at": null,
"finished_at": null,
"role_label": "Collaborator"}
Actions
List request
Lists all collaborations the user is involved with
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/user/collaborations | Collection | 200 OK |
Parameters
This action does not have any parameters.
Get request
Shows details of the specified collaboration
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/user/collaborations/(user_collaboration_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Accept request
Accepts the collaboration giving access to the account
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/user/collaborations/(user_collaboration_id)/accept | Member | 200 OK |
Parameters
This action does not have any parameters.
Reject request
Rejects the collaboration
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
POST | /1.0/user/collaborations/(user_collaboration_id)/reject | Member | 200 OK |
Parameters
This action does not have any parameters.
Delete request
Ends an existing ‘accepted’ collaboration
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
DELETE | /1.0/user/collaborations/(user_collaboration_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Zone
A Zone represents cloud resources at a datacentre. Each Zone is completely isolated in terms of power, cooling, security and networking equipment.
Attributes
Attribute | JSON values | Type | Default | Example | Nested? | Collected? | Description |
---|---|---|---|---|---|---|---|
id | string | ZoneID | zon-8ja0a | true | true | Unique Identifier | |
url | string | URL | https://api.gb1.brightbox.com/1.0/zones/(zone_id) | true | true | URL to access details of resource | |
handle | string | String | gb1-a | true | true | The Zone handle |
Representations
Full Zone representation example
{"id": "zon-328ds",
"resource_type": "zone",
"url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
"handle": "gb1"}
Collection Zone representation example
[{"id": "zon-328ds",
"resource_type": "zone",
"url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
"handle": "gb1"}]
Nested Zone representation example
{"id": "zon-328ds",
"resource_type": "zone",
"url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
"handle": "gb1"}
Actions
List request
Lists summary details of zones available to the account.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/zones | Collection | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Get request
Get full details of the zone.
HTTP Method | URL | Returns | Normal response |
---|---|---|---|
GET | /1.0/zones/(zone_id) | Member | 200 OK |
Parameters
This action does not have any parameters.
Allowed Account states
This action can only be performed when the owning Account is in the following states:
Errors
There are two different styles of errors that the API may return depending on where the problem with the request occurred.
Authentication or access control errors use the OAuth2.0 format. This format provides a single error name and a description.
A single request may contain multiple errors so all errors relating to the API itself will return an error name and an array of errors.
Authentication errors
Requests related to authentication or authorization are implemented as specified in the OAuth2.0 specification.
HTTP/1.1 400 Bad Request
WWW-Authenticate: OAuth error="invalid_request"
{
"error": "invalid_request",
"error_description": "The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed."
}
As per the specification there is also a "WWW-Authenticate" header that contains the error name as well.
Request errors
When an error occurs for GET or POST requests, the content body includes a JSON object containing details of the error for the client to handle.
{
"error_name": "Forbidden",
"errors": [
"Account limit reached, please contact support for more information"
]
}
API Errors include more detailed messages where possible without giving out information to unprivileged users.
API Error | HTTP Code | Error summary |
---|---|---|
Unrecognised endpoint | Bad request (400) | The request was for an unrecognised API endpoint |
Unauthorized request | Unauthorized (401) | The API User doesn’t have permission to access that resource |
Account closed | Forbidden (403) | The account has been closed |
Account fraudulent | Forbidden (403) | Unable to complete the request. Please contact support@brightbox.com |
Account limit reached | Forbidden (403) | Account limit reached |
Account not verified | Forbidden (403) | The account has not yet been verified |
Account suspended | Forbidden (403) | The account is currently suspended |
Account terminated | Forbidden (403) | The account has been terminated |
Account verification pin incorrect | Forbidden (403) | PIN appears to be incorrect |
Action forbidden | Forbidden (403) | The API User is not permitted to carry out requested action |
Cloud ip allocation failure | Forbidden (403) | Cloud IP cannot be allocated |
Cloud ip release failure | Forbidden (403) | Cloud IP cannot be released |
Insufficient capacity | Forbidden (403) | Insufficient capacity available |
Insufficient instance capacity | Forbidden (403) | Insufficient server capacity available |
Missing resource | Not found (404) | Resource not found using supplied identifier |
Method not allowed | Method not allowed (405) | Invalid HTTP Method |
Cloud ip mapping failure | Conflict (409) | Cloud IP cannot be mapped or unmapped |
Cloud ip reserved error | Conflict (409) | Cloud IP is unable to be reserved for this server build |
Invalid transition | Conflict (409) | Unable to accept the request due to the current state of the resource |
Resource conflict | Conflict (409) | Unable to accept the request due to the current state of the resource |
Snapshot in progress | Conflict (409) | A snapshot is currently being made of the server |
Missing association | Unprocessable entity (422) | No associated %{resource} found with identifier = %{identifier} |
Unprocessable entity | Unprocessable entity (422) | The request contained errors and could not be completed |
Unrecognised parameter | Unprocessable entity (422) | This parameter is unrecognised: %{parameter} |
Resource locked | Locked (423) | Resource is locked. It must be unlocked before it can be deleted |
Internal server | Internal server error (500) | Unhandled exception has occured |
Not implemented | Not implemented (501) | This version of the API hasn’t implemented that request |