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 /v1/some/url?attributes=123&some=aaa 1548240417

PHP example

<?php
$time = time();
$method = 'GET';
$path = '/v1/user';
$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 = "/v1/user/self"
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 = "/v1/user/self"
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 = "/v1/user/self"
# 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
function hash_hmac {
  digest="$1"
  data="$2"
  key="$3"
  shift 3
  echo -n "$data" | openssl dgst "-$digest" -hmac "$key" "$@"
}
 
method="GET"
path="/v1/user/self"
api="https://rest.websupport.sk"
query=""
apiKey="ak48l3h7-ak5d-qn4t-p8gc-b6fs8c3l"
secret="ajvkeo3y82ndsu2smvxy3o36496dcascksldncsq"
signature=$(hash_hmac "sha1" "${method} ${path} $(date +%s)" "${secret}")
 
curl "${api}${path}${query}" -u "${apiKey}:$(echo $signature | cut -d " " -f2)" -H "Date: $(date +%Y%m%dT%H%M%SZ --utc)" -H "Accept: application/json" -H "Content-Type: application/json"

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:

The communication through API is using UTF-8 encoding.

Allowed HTTPs requests

Most frequent server response descriptions

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.

raw