Connecting to API

This API is based on REST principles.

API authentication

We use HTTP Basic authentication where username is the api key and password is the calculated request signature that changes with every request. The secret should never be sent, instead it's used to generate the request signature. Api key and secret can be generated in our Admin.

The signature is a hex-encoded HMAC-SHA1 hash calculated from the canonical request using provided secret.

Canonical request takes form of {http method} {complete request path} {unix timestamp}, e.g. GET /v2/some/url?attributes=123&some=aaa 1548240417

PHP example

                    
<?php
    $time = time();
    $method = 'GET';
    $path = '/v2/service/%s/dns/record';
    $api = 'https://rest.websupport.sk';
    $query = ''; // query part is optional and may be empty
    $apiKey = 'ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l';
    $secret = 'ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq';
    $canonicalRequest = sprintf('%s %s %s', $method, $path, $time);
    $signature = hash_hmac('sha1', $canonicalRequest, $secret);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, sprintf('%s%s%s', $api, $path, $query));
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    curl_setopt($ch, CURLOPT_USERPWD, $apiKey.':'.$signature);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Date: ' . gmdate('Ymd\THis\Z', $time),
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    echo $response;
                    
                

Python2 example

                    
import hmac
import hashlib
import time
import requests
import base64
from datetime import datetime

method = "GET"
path = "/v2/service/%s/dns/record"
timestamp = int(time.time())
api = "https://rest.websupport.sk"
query = "" # query part is optional and may be empty
apiKey = "ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l"
secret = "ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq"
canonicalRequest = "%s %s %s" % (method, path, timestamp)
signature = hmac.new(secret, canonicalRequest.encode('utf-8'), hashlib.sha1).hexdigest()

headers = {
   "Content-Type": "application/json",
   "Accept": "application/json",
   "Date": datetime.fromtimestamp(timestamp).isoformat()
}

print requests.get("%s%s%s" % (api, path, query), headers=headers, auth=(apiKey, signature)).content
                    
                

Python3 example

pip3 install requests

                    
import hmac
import hashlib
import time
import requests
import base64
from datetime import datetime, timezone

method = "GET"
path = "/v2/service/%s/dns/record"
timestamp = int(time.time())
api = "https://rest.websupport.sk"
query = "" # query part is optional and may be empty
apiKey = "ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l"
secret = "ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq"
canonicalRequest = "%s %s %s" % (method, path, timestamp)
signature = hmac.new(bytes(secret, 'UTF-8'), bytes(canonicalRequest, 'UTF-8'), hashlib.sha1).hexdigest()

headers = {
	"Content-Type": "application/json",
    "Accept": "application/json",
    "Date": datetime.fromtimestamp(timestamp, timezone.utc).isoformat()
}

print(requests.get("%s%s%s" % (api, path, query), headers=headers, auth=(apiKey, signature)).content)
                    
                

PowerShell 7 example

                    
$api_id = "ak48l3h7-ak5d-qn4t-p8gc-b6fs8c31"
$api_secret = "ajvkeo3y82ndsu2smvxy3o36496dcascksldncs1"
$current_time = Get-Date -UFormat %s
$method = 'GET'
$api = "https://rest.websupport.sk"
$path = "/v2/service/%s/dns/record"
# query part is optional and may be empty:
$query = ""
$canonical_request = "$method $path $current_time"
$hmacsha = New-Object System.Security.Cryptography.HMACSHA1
$hmacsha.key = [Text.Encoding]::ASCII.GetBytes($api_secret)
$signature_byte = $hmacsha.ComputeHash([Text.Encoding]::ASCII.GetBytes($canonical_request))
$signature = ($signature_byte|ForEach-Object ToString x2) -join ''
$base64EncodedString = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(($api_id+":"+$signature)))

$Headers = @{
    'Authorization' = "Basic $base64EncodedString"
    'Content-Type' = "application/json"
    'Accept' = "application/json"
    'Date'   = (Get-Date $current_time).ToString('yyyy-MM-ddTHH:mm:ss')
}

$parameters = @{
    Uri         = "$api$path$query"
    Headers     = $Headers
    Method      = $method
}

Invoke-RestMethod @parameters
                    
                

Shell example

                    
#!/bin/bash
time=$(date -u +"%s")
method="GET"
path="/v2/service/%s/dns/record"
api="https://rest.websupport.sk"
query=""
apiKey="ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l"
secret="ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq"

canonicalRequest="${method} ${path} ${time}"
signature=$(echo -n "$canonicalRequest" | openssl dgst -sha1 -hmac "$secret" | awk '{print $2}')
jsonData='{}'

$(curl -s -X $method "$api$path$query" \
    -H "Date: $(date -u +"%Y%m%dT%H%M%SZ")" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -u "$apiKey:$signature" \
    -d "$jsonData")
                    
                

Please add Authorization: header to all requests. Example: Authorization: Basic aHR0cHdhdGNoOmY= (last string is base64 encoded version of <apiKey>:<signature>) Additionally all request must contain a valid Date header with the time used for the signature in the ISO8601 basic format, in the GMT timezone.

Connection is encrypted with SSL, so all your requests are safe.

Request and response formats

This API is using JSON format in both directions. Please add these two headers to your request:

• Content-Type: application/json
• Accept: application/json

The communication through API is using UTF-8 encoding.

Allowed HTTPs requests

• GET: to get a resource or list of resources
• PUT: to update resource
• POST: to create resource
• DELETE: to delete resource

Most frequent server response descriptions

• 200 OK - the request was successful (however some API calls may return 201 instead)
• 201 Created - the request was successful and the resource was created
• 204 No Content - the request was successful, but there is no representation to return (i.e. the response is empty)
• 400 Bad Request - the request could not be understood or was missing parameters required
• 401 Unauthorized - authentication failed or user doesn't have permissions for requested operation
• 403 Forbidden - access denied
• 404 Not Found - resource was not found
• 500 Internal Server Error - something bad happened
• 501 Not Implemented - you are calling a not implemented method

Messages above 400 are in the following format:

response 400

                    
{
    "code": 400,
    "message": "This is an example error message!"
}
                    
                

Language

API supports different languages in validation messages. You can change language with header Accept-Language: en_us. Supported languages are: en_us, sk, cs_cz, hu.