REST API

Кожен шлях на цій сторінці лежить за наведеною нижче базовою URL-адресою, і кожен запит несе ваш ключ у заголовку Authorization. Іншого входу немає: ні сеансового cookie, ні basic auth, ні ключа в рядку запиту.

curl -s https://app.provibr.com/api/v1/me \
  -H "Authorization: Bearer pvk_..."

Ключ ви створюєте у власному профілі, у розділі Ключі API. Він належить вам і одному обліковому запису: ним не діляться з колегами, і він перестає працювати тієї миті, коли ви залишаєте цей обліковий запис.

• Ключ діє 90 днів, якщо ви не оберете інакше. Можна взяти коротший строк або не брати жодного; ключ без дати завершення — це ключ, про відкликання якого доведеться памʼятати вам самим.
• Ротація означає створити новий ключ і відкликати старий, лишивши проміжок, у якому працюють обидва. Ротації на місці немає, бо вона лишає вас без робочого ключа, якщо на півдорозі щось піде не так.
• Ключ можна привʼязати до переліку адрес. Запит з будь-якої іншої адреси відхиляється ще до того, як щось буде прочитано, і ця відмова нічого не повідомляє про ключ тому, хто звернувся.
• Один учасник тримає щонайбільше 25 ключів. Відкликаний ключ зберігає свій рядок, тож і потім видно, що йому було дозволено, доки він діяв.

Ключ несе права: читання або запис, для кожної частини панелі. Що він може насправді — це перетин прав ключа і прав учасника, якому він належить.

Права читаються наживо, під час кожного запиту. Заберіть щось в учасника, і кожен його ключ одразу стає вужчим, без потреби щось відкликати. Саме тому ключ переживає зміну ролі, а не скасовується нею.

Ваша інфраструктура доступна лише через агента у вашій власній мережі, а той агент підключається назовні. Тож кінцева точка, яка змінює машину, не може відповісти результатом. Вона відповідає, що доручення прийнято, і дає вам те, за чим стежити.

1. 01Ви надсилаєте запит і отримуєте відповідь про прийняття, із заголовком Location, що вказує на створену команду. Цей заголовок є абсолютним від хоста: розвʼязуйте його відносно джерела, а не відносно базової адреси вище, інакше ви запитаєте шлях, якого не існує.
2. 02Ця сама команда є і в тілі відповіді, але загорнута в поле command. Читання нижче повертає її голою, без цієї обгортки: розгорніть її один раз, і перше читання зазвичай зайве.
3. 03Ви читаєте команду, доки її стан не стане остаточним: виконано, не вдалося, термін минув або скасовано. Лише в очікуванні не є остаточним, а стан, якого ви не знаєте, також вважається остаточним, тож додане пізніше значення ніколи не змусить вас читати вічно.
4. 04Команда, яка не вдалася, несе код помилки самого агента разом з його аргументами, тими самими, які панель показує на вашому екрані.

# 1. the order - answers 202 with a Location header
curl -s -D - -X POST https://app.provibr.com/api/v1/servers/<serverId>/actions/start \
  -H "Authorization: Bearer pvk_..."

# 2. the outcome - repeat until the status is final
curl -s https://app.provibr.com/api/v1/commands/<commandId> \
  -H "Authorization: Bearer pvk_..."

Кожна кінцева точка каже, чим вона відповідає: 200 для читання, 201 коли щось створено, 202 коли вашому агенту ще належить попрацювати. І кожна описує тіло, яке повертає, з власною назвою для кожного ресурсу, тож згенерований код має один тип на ресурс, а не один на кінцеву точку.

Переліки відповідають сторінкою і курсором; ви передаєте той курсор назад, доки він не повернеться порожнім. За замовчуванням сторінка містить 50 рядків, а щонайбільше — 100 рядків.

Кожна відповідь, яка не є успіхом, має однакову форму, незалежно від того, що і де пішло не так.

{
  "error": {
    "code": "validation_failed",
    "message": "Name is too long (max 64).",
    "detail": "server.validation.apiKeys.nameTooLong",
    "params": { "max": 64 },
    "requestId": "3f9c1b2a-..."
  }
}

code

Слово, за яким ви розгалужуєтеся. Воно походить із закритого переліку, тож невідоме вам значення означає, що ви говорите з новішою версією, ніж та, під яку ви писали.

message

Одне речення англійською призначене для того, хто читає журнал. Ніколи не розгалужуйтеся за ним: формулювання може змінитися будь-коли.

detail

Стабільний ключ, там, де він є. Це той самий ключ, який панель використовує для власного повідомлення, тож ви можете подати це речення своєю мовою.

params

Аргументи, що належать цьому ключу: перевищена межа, вже зайняте імʼя, хост, який відмовив.

requestId

Ідентифікатор цього запиту, він же в заголовку відповіді. Наводьте його, коли про щось нас запитуєте.

Ви можете робити 120 запитів за хвилину на кожен ключ і 600 запитів на обліковий запис, разом за всіма його ключами. Друга межа існує, щоб двадцять ключів не могли створити вдвадцятеро більше навантаження на той самий хост.

Усе, що щось створює, приймає заголовок idempotency-key, який ви складаєте самі. Повторіть той самий запит із тим самим значенням, і ви отримаєте назад перший результат, а не другу машину, другий ключ чи другу команду.

Ви можете надіслати і власний x-request-id. Він повертається у відповіді й потрапляє до наших журналів — це найдешевший спосіб покласти ваш рядок поряд із нашим.

У маршрутизації цього API немає жодної назви провайдера. На запитання, які системи ви можете підключити, яких полів вимагають їхні облікові дані і що вони вміють, відповідає кінцева точка виявлення, а тіло, яке ви надсилаєте для створення інтеграції, будується з того самого реєстру. Провайдер, який стає доступним, зʼявляється в обох місцях без жодної зміни кінцевих точок.

Це працює і у зворотний бік. Попросіть чогось у машини, провайдер якої цього не вміє (консоль на обліковому записі хостингу, диск на ігровому сервері), і ви отримаєте відмову, яка називає відсутню можливість, ще до того, як щось піде до вашого агента.

Згруповані так, як їх групує специфікація. Кожен шлях іде після базової URL-адреси, а поряд стоїть право, якого вимагає кінцева точка; де не стоїть нічого, достатньо чинного ключа.

Та сама інформація у вигляді документа OpenAPI 3.1, згенерованого з коду, який обслуговує ці кінцеві точки, а не написаного поряд із ним. Передайте його генератору клієнтів, редактору або набору тестів.

curl -s https://app.provibr.com/api/v1/openapi.json

У межах цієї версії зміни — це доповнення: нові кінцеві точки, нові необовʼязкові поля, нові значення в переліку. Читайте поблажливо поля, яких ви не знаєте, і не вважайте фатальним код помилки, якого ви не знаєте.