ZoneID API (2.0)

Download OpenAPI specification:Download

ZoneID APIv2 is JSON based RESTful API for managing Domain, Webhosting, Cloudserver VPS and DNS services.

Authorization

HTTP basic auth is used for authentication:

  • username is ZoneID username
  • password is API key that can be generated under ZoneID account management

Use following header:

Authorization: Basic base64(zoneid_username:zoneid_api_token)

basic_auth

Security Scheme Type HTTP
HTTP Authorization Scheme basic

URL format and usage

URLs are built as:

https://api.zone.eu/v2/{service_type}/{service_name}/{resource_name*}/{resource_identificator*}

Where

{service_type} is

  • Domain: domain
  • Webhosting: vserver
  • DNS: dns
  • Cloudserver VPS: cloud

{service_name} is

  • Domain: domain name (e.g. example.com)
  • Webhosting: virtual server name (e.g. example.com)
  • DNS: Nameserver zone name (e.g. example.com)
  • Cloudserver VPS: VPS host name (e.g. uvn-XX-XXX.tll01.zonevs.eu)

Additional child endpoints may follow as /{child}/{child_identificator*}

* optional

For example to get single DNS A record, we use following url:

https://api.zone.eu/v2/dns/example.com/a/1

or to get all DNS A Records, we use following url:

https://api.zone.eu/v2/dns/example.com/a

There is exception for service ordering endpoints where path is build as:

https://api.zone.eu/v2/order/{service_type}

Requests

Request types are divided into 4 separate HTTP codes.

Code Description
GET Access one or more resource. All resources are returned in array. Single resources are returned as single array element. When accessing single resourse, then URL must end with giver resource identificator
POST Create new resource. Resouce data in JSON structure should be sent in request body. Generated resource is returned in response as single array element.
PUT Update existing resource. URL must contain given resource identificator of resource that is updated. Otherwise same as POST request
DELETE Delete existing resource. URL must contain given resource identificator.

Responses

Standard HTTP status codes are used to give feedback about operation. In addition, human readable response message is sent in header X-Status-Message. Using response message in your scripts is not recommended as these may change without warning. Descriptions of all HTTP standard status codes are here. Most commonly used in ZoneID API are:

Code Description
200 successful GET request
201 successful POST/PUT request
202 successful POST/PUT request in case request was accepted, but will be processed later (for example ordering new services)
204 successful DELETE request
422 unsuccessful request in case resource in request has validation errors. Error codes in response are in same structure as resource itself.
400 unsuccessful request in case request itself is invalid
402 unsuccessful request in case payment is required for further actions. Mostly used when package upgrade is required.

Rate limit

The number of request is limited to 60 per minute per IP.

Rate limit information is contained in every response headers.

  • X-Ratelimit-Limit The number of request that is allowed to be made in a minute
  • X-Ratelimit-Remaining The number of remaining requests until reset

If you have reached the rate limit, then HTTP response code 429 is returned

Use common sense

Don't create requests without need. Don't update resources that are not modified and don't ask for data that you already know.

For example when writing custom dynamic DNS style script for DNS A record, then.

  • Update IP only when it's changed and don't post same data again.
  • Keep track of last IP on your side and don't ask it from API after every n minutes to compare it with current one.

Pagination and sorting

On some GET endpoints we have enabled pagination. In that case there is header x-pager-enabled is sent in response.

Response headers describing pager:

Header Description
x-pager-enabled 1 when pager is enabled
x-pager-page Current page number
x-pager-pages Total number of pages
x-pager-limit Items per page
x-pager-items Total number of items

Request headers to use pager:

Header Description
x-pager-page Current page number
x-pager-limit Items per page. Default is 10 and maximum is 100
x-order-by Sort by field. Sortable fields are described in Resource documentation
x-order-dir Sort direction: asc or desc

Examples

Example CURL request to get DNS A record

curl -X GET https://api.zone.eu/v2/dns/example.com/a/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic em9uZWRfdXNlcm5hbWU6em9uZWlkX2FwaV9rZXk='

Example CURL request to create DNS A record

curl -X POST https://api.zone.eu/v2/dns/example.com/a \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic em9uZWRfdXNlcm5hbWU6em9uZWlkX2FwaV9rZXk=' \
-d '{"name": "prefix.example.com","destination": "123.123.123.123"}'

Successful GET, POST and PUT responses always contain requested (or created/updated) resource(s). For example:

[
    {
        "id": "123",
        "resource_url": "https://api.zone.eu/v2/dns/example.com/a/123",
        "name": "prefix.example.com",
        "destination": "123.123.123.123",
        "delete": true,
        "modify": true
    }
]

DNS

Get DNS zone

Authorizations:
path Parameters
service_name
required
string

Unique name of service.

Responses

Response Schema: application/json
Array ()
resource_url
string

API url to get this entity

identificator
string

identificator

active
boolean

Is zone active

ipv6