Connecting to API
=================

This API is based on [REST](http://en.wikipedia.org/wiki/Representational_state_transfer) 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
<?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**
```python
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`

```python
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**

```bash
#!/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:

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

The communication through API is using [UTF-8 encoding](http://en.wikipedia.org/wiki/UTF-8).

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`
```json
{
    "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`.