This API allows resellers to manage their resources in a simple, programmatic way using HTTP requests.
The API supports different methods depending on the required action.
|GET||Retrieve resources in a collection or get a single resource.|
Getters will never have any effect on the queried resources.
|POST||Create a new resource in a collection.|
|PUT||Update an existing resource with its new representation.|
|DELETE||Delete an existing resource.|
The API will reply with different HTTP statuscodes:
|200 OK||The requests was processed and you receive data as a result.|
|201 CREATED||The resource has been created. Either the Location header contains a link to the created resource, or links are being returned in the response body. The applied method will be indicated in the documentation.|
|202 ACCEPTED||The request has been validated and accepted. Because we need to do some background processing prior to returning the result, we cannot send back a useful representation.|
|204 NOCONTENT||The request has been processed, but no details can be returned.|
|400 BADREQUEST||Your request is malformed.|
|401 UNAUTHORIZED||You are not authorized. Follow the instructions in the Authorization documentation.|
|403 FORBIDDEN||Access to the resource or operation is not allowed.|
|404 NOTFOUND||The resource cannot be found.|
|410 GONE||The resource is permanently no longer available.|
|429 TOOMANYREQUESTS||The ratelimit has been exceeded. Please refer to the documentation on rate limiting for more details.|
|500 INTERNALSERVERERROR||An error occurred during the processing of the request. The error is unexpected and most likely due to a bug in the api.|
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.
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 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.
|X-Paging-Skipped||The number of results that have been skipped.|
|X-Paging-Take||The number of items in the current take. The number might differ from the requested take. It represents the actual number of items returned in the response.|
|X-Paging-TotalResults||The total number of results regardless of paging.|
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.
|X-RateLimit-Limit||The number of requests that can be made in a specific time interval.|
|X-RateLimit-Usage||The number of requests already made in the current time interval.|
|X-RateLimit-Remaining||The number of requests remaining until the reset.|
|X-RateLimit-Reset||The number of seconds until the reset.|
After the reset you are allowed to make as many requests as specified by the X-RateLimit-Limit header.
|Retry-After||The number of seconds you have to wait until you can make new requests.|
This header is only present when the rate limit has been reached. It is identical to X-RateLimit-Reset.
When the ratelimit has been reached, all requests will return with a HTTP statuscode 429 and ReasonPhrase ‘Too many requests, retry later.’.
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.
|apikey||The key that is linked to your user.|
|request method||lowercased (eg: get, post, delete,…)|
|path and querystring information||urlencoding of the lowercased relative path and querystring.|
The path MUST start with the api version (/v2).
The hexadecimal codes (percent encoding) MUST be uppercased.
|unix timestamp||the unix timestamp in seconds.|
|nonce||a unique string for each request. It should be a random string, not related to the request. The nonce (in combination with the unix timestamp) protects you from replay attacks in case anyone was able to intercept a request.|
|content||When the request body is not empty, this should be the Base64 encoded Md5 hash of the request body.|
An empty body should not be encoded.
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:
A sample (illustrated):
Access is by default restricted for all IP addresses. You need to explicitly whitelist an IP or an IP range in your controlpanel.
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.
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.
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.
|Servicepack||Defines a set of assets that belong together. An example is a hosting package which offers Linux hosting, a domain name, a couple of mailboxes and databases.|
It also limits the size of individual assets within the same account.
|Account||Represents an instance of the servicepack. It contains one or more assets. The number and size of assets is defined by the servicepack.|
|Asset||A manageable service. For example: a mysql database, a linux hosting, a mailbox,…|
Some assets are created at the moment when the account is created. Other assets can be created afterwards.
Provisioning of an account with Linux hosting with one MySql database
Without a pre-existing account:
Requesting an SSL certificate causes the purchase of a paying product.
Use this page to mock Public Api in your testing and development.
Run our mock API sample using the open source WireMock library, or in the free edition of WireMock Cloud. You'll have a working API server simulating the behavior of Public Api, which will allow you to keep building and testing even if the actual API you isn't currently available.