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!

Guides
 

Welcome to our API documentation! You can view code examples in the area to the right.

For more information about Maxihost products, you can visit our product documentation.

Suggest Edits

API Summary

 

JSON is returned in all responses.

The API also uses common approaches for the following:

Function
Description

Data

API data is JSON encoded with UTF-8. API JSON is either a single object or a list of objects.

Authorization

Access control using API Access Tokens.

Errors

4xx and 5xx responses returning JSON with error codes

HTTP

Methods are used in accordance with HTTP (GET POST and DELETE are the primary methods used) and resources are identified using URIs. All API requests are sent over HTTPS.

Suggest Edits

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.

$ curl \
-s https://api.maxihost.com/users/494817923 \
-H "Authorization: Bearer <access_token>" \
-H 'Accept:application/json'
Suggest Edits

Versioning

 

In order to use version 1.1, all you have to do is send the following header on your request:

Accept: application/vnd.maxihost.v1.1+json

Suggest Edits

Error Objects

 

The API will return an Error List for a failed request, which will contain one or more Error objects.

Error List Attributes

Each error has the following attributes

Field
Description

status

The status is false

code

General context about the error. See Error Codes.

error_messages

An array of one or more error objects.

Error Object Attributes

Each Error Object has the following attributes

Field
Description

base

Human readable description of the error

Error List Object

{
  "status": "error.list",
  "errors": [
    {
      "code": "not_found",
      "message": "No such user_id[494817923]",
      "field": "user_id"
    },
    {
      "code": "not_found",
      "message": "No such email[john@doe.acme]",
      "field": "email"
    }
  ]
}
Suggest Edits

Error Codes

 

The API may send the following error codes. Other codes may be added in the future.

Field
Description

CLIENT_ERROR

Generic server error

TIMEOUT

Timeout error

UNAUTHORIZED_REQUEST

The request was not authorized. Check your token.

FORBIDDEN_REQUEST

The request was forbidden. Check your token.

INVALID_CREDENTIALS

The credentials are invalid. Check your data.

UNPROCESSABLE_ENTITY

Cannot process the request. Check your data.

INVALID_TOKEN

The token is invalid. Request a new token.

REVOKED_TOKEN

The token is revoked. Request a new token.

MISSING_TOKEN

The token is missing. Check your token.

EXPIRED_TOKEN

The token is expired. Request a new token.

ACCOUNT_LOGIN_FAILURE

Failure to log in. Check your credentials.

MALFORMED_PAYLOAD

Your payload is wrong. Check your data.

PRIMARY_USER_EDIT

Cannot update the primary user. Select another user to update.

<ITEM>_NOT_FOUND

<ITEM> not found. Check your data.

UPDATE_CONTACT

Failure updating a contact. Check your data.

NOT_FOUND

Generic error when the subject is not found

INVALID_UPDATE

Failure updating the subject. Check your data.

<ITEM>_LIST_FAILURE

Failure listing available <ITEM>. Try again later.

<ITEM>_UPDATE_FAILURE

Failure updating <ITEM>. Try again later.

<ITEM>_CREATE_FAILURE

Failure creating <ITEM>. Try again later.

Suggest Edits

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.

Suggest Edits

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.

 

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 " ' & < >

Let's say you have a company name like "BL&T's". 
Then when you retrieve it from the API it will look like this:
"BL&amp;T&#39;s"
Suggest Edits

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.

Suggest Edits

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. Pagination can also be toggled off via ?limit=0 query string

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

"links": {
        "first": "https://api.maxihost.com/devices?limit=2&page=1",
        "last": "https://api.maxihost.com/devices?limit=2&page=10",
        "next": "https://api.maxihost.com/devices?limit=2&page=3",
        "prev": "https://api.maxihost.com/devices?limit=2&page=1",
        "self": "https://api.maxihost.com/devices?limit=2&page=2"
    },
    "meta": {
        "pages": {
            "count": 2,
            "total": 10
        }
    }
name
description

first

The first page. Included when the current page is greater than 1

last

The last page

next

The next page. Included when there's a next page

prev

The previous page. Included when there's a previous page

self

The current page

meta/pages/count

The total number of resources

meta/pages/total

The total number of pages

Suggest Edits

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.

Suggest Edits

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.

Unknown Field

{
  "type": "user",
  "user_id" : "456456",
  "email" : "j@example.org",
  "such_key": "so_value"
}

Must Ignore Interpretation

{
  "type": "user",
  "user_id" : "456456",
  "email" : "j@example.org"
}