Початок роботи

У цьому розділі описано Web API платформи, реалізований як REST-API з обміном даними у форматі json.

Загальні положення

• Формат передавання даних Web API реалізовано як REST-API з обміном даними у форматі json.
• Процедура автентифікації Автентифікація ґрунтується на токені, що динамічно оновлюється: це гарантує безпеку отриманих даних і запобігає витоку токена.
• Формат змінних, що містять дату й час Web API повертає дані типу «дата й час» у кодуванні UNIX time або POSIX time у форматі UTC: 1613376963. Перетворюючи Unix time на дату у зрозумілому форматі, обов’язково вказуйте часовий пояс.
• Посторінкова розбивка (pagination) У Web API реалізовано посторінкову розбивку для завантаження даних сторінка за сторінкою. Передається параметром: page="page number" (page=1). Кількість записів, які повертає запит, можна задати параметром per_page, але не більше ніж 1000 записів.

Базовий URL

У всіх прикладах на цих сторінках використано такий базовий URL:

https://api.vadsro.eu/api/v1

Автентифікація

Автентифікація ґрунтується на токені, що динамічно оновлюється. На практиці це виглядає так:

• Первинна автентифікація виконується за наявними в системі електронною поштою та паролем; у відповідь надходять динамічний токен і пов’язані з ним атрибути.
• Формування цільового запиту на отримання даних — до заголовків HTTP-запиту додається токен, отриманий на попередньому кроці.
• Надсилання запиту на сервер. Якщо запит сформовано правильно, сервер повертає дані в тілі відповіді та новий токен у заголовках відповіді, а старий токен стає недійсним. З новим токеном можна повторити попередній крок — і так далі.
• Після завершення роботи останній токен можна зробити недійсним ще до закінчення терміну його дії (SignOut).

Початкова автентифікація виконується за електронною поштою та паролем наявного користувача. Для цього потрібно надіслати POST-запит на адресу:

https://api.vadsro.eu/api/v1/auth/sign_in

Приклад запиту у форматі Curl:

curl -i --header "Content-Type: application/json" \
     --request POST \
     --data '{"email":"api-user@example.com","password":"Str0ngPas$"}'\
     https://api.vadsro.eu/api/v1/auth/sign_in

У відповідь отримаємо таке повідомлення:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-1
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615227012
uid: api-user@example.com
ETag: W/"5b9bcc76f7223b72b79d9f2d31ff0fd5"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: c18e06b4-e5bd-40b5-875d-7ac958e2fbb5
X-Runtime: 0.391069
Transfer-Encoding: chunked
{"data":{"id":6,"email":"api-user@example.com","provider":"email","uid":"api-user@example.com","name":"API user"}}

У цій відповіді нас цікавлять такі заголовки:

Приклад запиту з використанням токена з попередньої відповіді:

curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-1" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"page":"2"}' \
 https://api.vadsro.eu/api/v1/stations

У відповідь отримаємо таке повідомлення:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-2
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615311367
uid: api-user@example.com
ETag: W/"ba0df406b647bd92f0bf3a18916714c1"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 35a26441-ae78-48fa-8b2e-e92d2605133b
X-Runtime: 0.167748
Transfer-Encoding: chunked
{"data": [
{"id":1,"name":"860000000000001","equipment_brand_name":"Corrector BK","phone":"","equipment_id":1},...
 ],
"total_pages":7,
"current_page":2
}

Щоб завершити роботу, можна скористатися процедурою SignOut або зберегти потрібні заголовки з останнього запиту і, якщо термін дії токена ще не минув, використати їх наступного разу.

Завершення сеансу:

curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-2" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request DELETE \
 https://api.vadsro.eu/api/v1/auth/sign_out
HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
ETag: W/"c955e57777ec0d73639dca6748560d00"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: b4b69ac3-5cba-4e6e-b6a0-f6577298c166
X-Runtime: 0.141467
Transfer-Encoding: chunked
{"success":true}

Наступні кроки

Тепер, коли ви можете виконувати автентифікацію, ознайомтеся з основними ресурсами API: