Introduction

This API allows resellers to manage their resources in a simple, programmatic way using HTTP requests.

Conventions

Requests

The API supports different methods depending on the required action.

HTTP status codes

The API will reply with different HTTP statuscodes:

In the event of a problem, the body of the response will usually contain an errorcode and errormessage. In rare cases additional details about the error are reported.

Errorcodes 400-499 are considered to be client errors and indicate that there was an issue with the request. We will not take any action besides monitoring.

Errorcodes 500-599 are considered to be server errors. The errors are monitored AND action will be taken to resolve the error.

Formatting

Snake casing is applied on resources and query parameters. The API is strictly returning JSON. No other formats are supported.

Datetimes are returned in ISO-8601 format.

Pagination

Pagination is on by default on collections and is controlled by specifying skip and take parameters.
Skip indicates the number of results to skip and where to start the new take.
Take indicates the number of records to return. The returned number of items can be smaller than the requested take.

Paged results will have headers with useful information regarding the paging.

Rate limiting

The number of requests per interval is limited. Detailed information on the rate limiting can be found in specific headers which will be sent on each request.

When the ratelimit has been reached, all requests will return with a HTTP statuscode 429 and ReasonPhrase 'Too many requests, retry later.'.

Authentication

The Api uses HMAC authentication.
Hash-based message authentication code (HMAC) is a mechanism for calculating a message authentication code involving a hash function in combination with a secret key.
Both the integrity and the authenticity of the message are verified this way.

Steps to generate the HMAC

1. Get your api key and secret from your controlpanel.
   It is absolutely vital that the secret is never exposed. Once the secret is out, anyone would be able to generate hmacs to impersonate you.
   In case your secret is compromised, you can generate a new api key and secret on your controlpanel.
2. Construct the input value for generating the hmac.
   Concatenate:apikey, request method, path and querystring information, unix timestamp, nonce and content.

3. Hash the concatenated string using your api secret and the SHA-256 algorithm.
4. Base64 encode the result of the hash function. This is the hmac signature you will need to send an authorized request.

Sending an authorized request

An authorized request can be made by sending the generated HMAC in the authorization header.
A correct authorizationheader uses the hmac authorization scheme and a correctly formatted authorization parameter.

Create the authorization parameter by concatenating:

• apikey
• colon ':'
• generated HMAC signature (see above)
• colon ':'
• nonce (the one used to generate the signature)
• colon ':'
• unix timestamp (the one used to generate the signature)

A sample (illustrated):

• The first line is the string you create to feed to the hashing algorithm.
• The second line is the authorization header that should be sent in the request.

IP whitelisting

Access is by default restricted for all IP addresses. You need to explicitly whitelist an IP or an IP range in your controlpanel.

Versioning

Because of breaking contract changes compared to v1, we released v2 of the API.
V1 will still be available, but you are strongly encouraged to migrate to the latest version.
New features will only be available on v2.

Policy

Fair use policy

Please respect the rate limits and do not use the api for any purposes of abuse.
All requests are being monitored and logged.
Intentional abuse might result in api key revocation.

Errors

The API attempts to return appropriate HTTP status codes for every request.
When the status code indicates failure, the API will also provide an error message in most cases.

An error message contains a machine-parseable error code accompanied by a descriptive error text.
The text for an error message might change over time, but codes will stay the same.

An overview of error codes can be found here.

Change log

An overview of new changes can be found here.

Provisioning information

Terminology

Common provisioning scenario

Provisioning of an account with Linux hosting with one MySql database

Without a pre-existing account:

1. Create a new account.
   Perform a POST on the accounts route and provide the desired servicepack id and identifier (domain name).
2. Read the Location header from the response and perform a GET of the provided resource (a provisioning job).
3. When the response returns 200(OK), you should repeat the GET operation after a certain interval (Repeat this step).
   When the response returns 201(Created), you should read the response body. This will contain links to the created resources.
   This will usually hold only one link, but to be futureproof, this has been designed to return a collection.
4. The created resource will point to an account. You now know the account's Id and can continue with the provisioning of a MySql database on this account.
5. Perform a POST on the mysqldatabases route and provide the account id along with other requested information.
6. Read the Location header from the response and perform a GET of the provided resource (a provisioning job).
7. When the response returns 200(OK), you should repeat the GET operation after a certain interval (Repeat this step).
   When the response returns 201(Created), you should read the response body. This will contain links to the created resources.
   This will usually hold only one link, but to be futureproof, this has been designed to return a collection.
8. The created resource will point to a MySql database resource.

SSL certificate requests

Requesting an SSL certificate causes the purchase of a paying product.

1. A certificate is created by adding an ssl certificate request.
2. Upon statuscode 201 you should query for certificate completion on the resource provided in the location response header.
3. The resource request can respond with different statuscodes:

• 200: the certificate request is ongoing.
  Check the validations collection for validation values that are not auto_validated. Those should be set by you system.
  Call verify domain validations once all validation values are in place. It might take some time for verification to take place. It is not necessary to call this method more than once.
• 303: the certificate request is complete; there is no more certificate request resource available. Check the location header value to retrieve the representation of the resulting ssl certificate.
• 410: the certificate request does not exist anymore, there is no certificate created as a result of the request.