API

Програмний доступ до даних та дій системи — щоб ними можна було користуватися у власних інструментах, а не лише через наш екран.

• ОпераціїРодина
• в абонементі AURAОплата

Проблема

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

Що робимо

Відкриваємо дані та дії системи назовні так, щоб ними міг скористатися ваш програміст або ваш інструмент.

• Доступ видається і відкликається на стороні прав, а не надсиланням комусь пароля
• Обсяг визначаємо прямо: що йде назовні, а що залишається всередині
• До доступу додається документація, бо інтерфейс без опису — доступ лише на папері

Що входить

Три елементи; про другий вирішуєте ви, а не ми:

• Доступ до даних системи та до її дій
• Права: хто, до чого і на який термін
• Документація, що описує, як цим користуватися

Терміни

Модуль не запускається окремо — він вмикається разом з рівнем AURA. Скільки займе робота з вашого боку, залежить від того, до чого має вести доступ: підключити готовий інструмент — одне, написати свій — інше. Обсяг та термін такої роботи визначаємо до старту, а не в процесі.

Вартість

Програмний доступ не стоїть поруч із системою як окремий договір — він її частина і закінчується разом із нею. Отже у нього немає ні власного прайсу, ні власного терміну розірвання. Чи вмикати його взагалі й наскільки широко, визначають під час налаштування, разом з рештою прав.

Якщо з вашого боку потрібна окрема інтеграційна робота — зв'язок із системою, яку ми ще не підтримуємо, — це окрема послуга зі своєю ціною та своєю статтею: «API інтеграції».

Що ви отримуєте

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

Як порахувати реальне навантаження, перш ніж встановлювати ліміти доступу

Перш ніж питати про ліміт запитів, варто порахувати, скільки їх буде реально. Формула: запити_за_хвилину = кількість_активних_користувачів_інструменту × кількість_оновлень_за_хвилину_на_користувача.

• кількість_активних_користувачів_інструменту — скільки людей або процесів реально користуються доступом у конкретний момент, а не скільки мають до нього доступ загалом
• кількість_оновлень_за_хвилину_на_користувача — як часто ваш інструмент запитує дані; панель, що оновлюється раз на хвилину, — це не те саме, що запит раз на день

При п'яти користувачах, які запитують дані раз на хвилину, це п'ять запитів за хвилину — небагато. Та сама панель, що опитує раз на секунду, — це вже триста запитів за хвилину, і це питання, яке треба поставити до старту, а не після.

Три шляхи виведення даних назовні: ручний експорт, готова панель, програмний доступ

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

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

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

Коли програмний доступ не окупається

Чотири ситуації, в яких варто обрати щось інше:

• Ніхто з вашого боку не програмує і не замовляє це на постійній основі — доступ без того, хто ним користується, залишається ключем, який ніхто не бере
• Потреба разова, наприклад одноразове вивантаження для аудиту — простіший і дешевший ручний експорт
• Достатньо дивитися на дані час від часу, без потреби з'єднувати їх з іншим інструментом — готова панель у системі робить те саме дешевше
• Йдеться насправді про з'єднання з конкретною іншою системою, а не про сирий доступ до даних — це послуга «Інтеграції», а не ця

У цьому останньому випадку різниця не косметична: доступ дає сирі дані та документацію, інтеграція будує готове з'єднання між двома конкретними системами.

Що нам потрібно з вашого боку, щоб доступ мав сенс

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

• Технічна людина — програміст, інтегратор або ваш інструмент — яка реально користуватиметься доступом
• Чіткий обсяг: які дані та які дії мають виходити назовні, а які мають залишитися всередині
• Рішення, хто з вашого боку надає і відкликає права доступу, коли змінюється склад команди

Без цього останнього рішення доступ залишається прив'язаним до однієї людини на постійній основі — а це проблема, коли ця людина йде з компанії.

Як перевірити ефект через місяць без нашого звіту

Три речі видно на боці вашого інструменту, без входу до жодного нашого сервісу.

• Чи надходять запити взагалі — це видно в логах вашого інструменту або інтегратора
• Чи достатньо документації, щоб хтось новий, хто ніколи з нею не працював, запустив з'єднання самостійно
• Чи справді відкликання доступу в однієї людини миттєво обриває з'єднання, а не через кілька днів

Цей останній тест варто провести один раз, свідомо, — це простіший спосіб перевірити безпеку, ніж читати договір.

Чого доступ до API не робить

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

Ми також не обіцяємо конкретного часу відповіді чи безперервної доступності — це не сервісний договір із гарантованим SLA, а доступ у межах системи, якою ви користуєтеся щодня. І він не замінює стикування систем: якщо вам потрібне готове, постійне з'єднання з конкретною чужою системою, цим займається шар інтеграцій — поруч, у тій самій AURA.

Найпоширеніша помилка під час використання доступу до API

Спільний пароль замість окремих прав. Хтось ділиться одним ключем доступу з усією командою, бо так швидше, — а потім ніхто не знає, який інструмент ним користується, і відкликання ключа в однієї людини вимикає всіх одразу.

Ціна цієї помилки стає очевидною лише при розставанні зі співробітником або при збої: треба вимкнути все і запускати заново, замість того щоб просто відкликати доступ в однієї людини. Тому права ми видаємо поштучно, а не одним спільним ключем на всіх.

Чиї це дані і що відбувається, коли змінюється саме API

Дані, до яких ми надаємо доступ, — ваші: вони виникли з вашої діяльності і залишаються вашими незалежно від того, чи увімкнено програмний доступ узагалі.

• Доступ надається і відкликається на рівні прав, без зміни чогось у самій системі — відкликання доступу в однієї людини чи в усього інструменту не видаляє дані
• При розставанні з AURA програмний доступ закінчується разом з рештою системи, на тих самих умовах, що й усе інше — це не окремий договір, який треба розривати окремо
• Якщо ми самі змінюємо форму даних або спосіб їх отримання, ми робимо це як зміну версії, а не тиху перезаписку того, що вже працює, — старі інструменти не мають вимикатися за один день без попередження

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