Maxihost Developer Hub

Welcome to Maxihost's Developer Hub. Here you'll find comprehensive guides and documentation to help you start working with Maxihost as quickly as possible, as well as support if yo u get stuck. Let's jump right in!

Access Tokens

You'll need an Access Token if you want to use the API to access your own Maxihost data – for example, if you use the API with your own scripts to get data from your Maxihost account.

Setting up Access Tokens

Access Tokens should never be shared outside of your company

Access Tokens allow access to your private customer data in Maxihost. They should not be shared outside of your company. We cannot stress enough how important it is for you not to share your Token with anyone.

Creating your Access Token is simple and you can get a Token instantly.

To create your Access Token, go to the API page on the dashboard by clicking here or by clicking on API on the main menu.

Using your Access Token

Once you have created your Access Token you will see it in the same section of your Dashboard. You can edit or delete the token from here.

You can copy your token and use it in much the same way as you would use an API Key. The specifics will depend on how you are integrating with Maxihost.

To use your Access Token simply provide it as part of the authorization header when you make a request. Access Tokens use the bearer authorization header when you make a request. This just means you need to specify the bearer type in the header.

For more info on the bearer token framework please see the official spec.

Operating System to deploy. You get this from the /plans/operating-system endpoint.

billing_cycle

string

required

Periodicity the server should be charged. Currently, only 'monthly' is allowed.

backorder

boolean

Create device even if out of stock. Optional. Default: false

ssh_keys

array of strings

A list of SSH Key fingerprints or IDs for deployment. Optional

Response

Device created

id

integer

description

string

type

string

type_id

integer

label

string

service_id

integer

power_status

integer

specs

object

specs.cpu

string

specs.disk

string

specs.ram

string

location

object

location.facility_name

string

location.facility_code

string

location.facility_country

string

location.row_name

string

location.rack_name

string

location.rack_position

string

ips

array

Device create failure

status

boolean

error_messages

array

This creates a new device in the selected facility. All of the attributes must be set, with exception of backorder, to successfully create a server.

By default, the request will fail if there are no available servers matching your criteria unless you set the backorder parameter to true. In that case, the device will be added to a backorder queue where it'll be provisioned as soon as we have a server that matches your requirements. The team is also notified when a device enters the backorder queue so it can prioritize restocking of that server.

HTTP Responses

The API returns HTTP responses on each request to indicate the success or otherwise of API requests. The codes listed below are often used, and the API may use others. Note that 4xx and 5xx responses may be returned for any request and clients should cater for them.

Response Code

Description

200

Ok -- The request was successful.

201

Created -- The request was successful.

400

Bad Request -- General client error, possibly malformed data.

401

Unauthorized -- The API Key was not authorised (or no API Key was found).

403

Forbidden -- The request is not allowed.

404

Not Found -- The resource was not found.

422

Unprocessable Entity -- The data was well-formed but invalid.

429

Too Many Requests -- The client has reached or exceeded a rate limit, or the server is overloaded.

500

Server errors - something went wrong with Maxihost's servers.

This response is most likely a momentary operational error (e.g. temporary unavailability), and, as a result, requests should be retried once.

Object Model

Commond Fields

API objects have a type field indicating their object type. Each object in the API may be given an identifier, indicated via its id field, and will typically be addressable via a URI. Many objects will also have a created field indicating the object's creation date as a UTC Unix timestamp.

Dates and Timestamps

All temporal fields in the API are encoded as Unix timestamps and are by definition always treated as UTC. The most common time fields in the API are created and updated.

Paramater

Description

created_at

The time the object was created. In most, but not all cases, this is the time the object was created according to the API server.

updated_at

The time the object was last updated according to the API server.

Optional Fields

Unpopulated optional data is returned as follows

Number, String, and Boolean types may be returned as having null values.

Arrays and Objects may be returned as empty ([]{})

In general clients should be able to handle null and empty fields.

Metadata and Custom Attributes

Some object types, such as Devices, have a metadata field that allows clients to set custom-defined data about an object.

Encoding

Data is encoded as defined by JSON in RFC4627. The default encoding for APIs is UTF-8. Certain characters, such as Emoji may be handled as surrogate unicode pairs (see section '2.5. Strings' of RFC4627).

Some query parameters may need to be url encoded when sending - for example, the email parameter value used to query users should be encoded.

HTML Encoding

It should be noted that the following identifiers are encoded to protect from potential cross-site scripting attacks: 'name', 'user_id', 'company_id' and 'email'. As a result you may see these identifiers in their encoded format when you retrieve them via the API.Note that the characters we encode are double quote, single quote, ampersand, less than and greater than symbols i.e " ' & < >

Identifiers and URLs

All objects in the API have an id field indicating their logical identifier. Some objects may optionally also have a self field that indicates a URL or canonical address for the object.

Parameter

Description

id

A string that identifies the object within the API. The id field will not be larger than 128 characters (in SQL it corresponds to a varchar(128)).

self

A URL that addresses the object within the API. The self field will not be larger than 255 characters (in SQL it corresponds to a varchar(255)).

These fields must always be treated as opaque strings - no guarantees are made about the internal structure of the id or self fields for an object.

The id field is always defined by the API server and is guaranteed to be unique relative to the type field - this means no two user objects will have the same id field, but a user and a company may have the same value for their id fields.

Pagination

List resources in the API are paginated by default to allow clients to traverse data over multiple requests. In most cases we're geared towards a default pagination limit of 10 resources per page which can be overridden via ?limit=<number>&page=<page number> query parameters.

The Maxihost API provides a Link header according to RFC5988 that can be used to retrieve the next page.

Here's an example response header from requesting the third page of servers:Link: <https://api.maxihost.com/devices?page=3>; rel="next"

If the Link header is blank, that's the last page. The Maxihost API also provides the following pagination totals

Header

Description

X-Total-Count

Total number of resources you're fetching

X-Total-Pages

The total number of pages

The API also provides links and meta/pages nodes that provide additional pagination data. Here's an example from requesting ?page=2 of devices

Use of HTTP

Request methods are used in accordance with HTTP

GET is used to access resources and perform queries. The API does not allow modifications (creates, updates, deletes) to occur via GET.

POST is used to create or update resources. The preferred model for creation is to post JSON to a 'collections' resource - for example the collections resource for users is https://api.maxihost.com/users. PATCH is not currently used by the API.

DELETE is used to delete resources.

Responses use standard HTTP codes. Where there are client or server errors, a list of of one or more errors in JSON format is returned in the body - see "Errors" for more details.

The API may send cache directives where suitable, notably the ETag, Last-Modified and If-Modified-Since headers.

The Accept header must be used by a client used to indicate a preferred response for GET/HEAD requests. Requests without an Accept header of application/json may be rejected with a client error of 404 or 406. The Content-Type header should be used by clients to indicate the submitted format for POST/PUT requests.

Compatibility

JSON objects in the API follow a must ignore processing model, where clients are expected to ignore data fields they don't understand.

For example if the client saw the JSON as shown in the example on the right ('Unknown Field')and did not understand the such_key field, it must pretend the field wasn't there and will process the object as if it looked liked the object shown in 'Must Ignore'.

When fetching content, fields that are optional for API objects are indicated in the documentation - clients must not assume they will always be present. When submitting content, fields that are required to be sent by client are also indicated in the documentation - if these are not sent the API may reject the request.

In general the API may reject JSON where data is not valid or incomplete with a 422 Unprocessable Entity response and an error message explaining the issue.