API

API Aura: программный доступ к данным и действиям системы, с правами и документацией — чтобы пользоваться ими в своих инструментах, а не только на экране.

• ОперацииСемейство
• в абонементе AURAОплата

Проблема

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

Что делаем

Открываем данные и действия системы наружу так, чтобы ими мог воспользоваться ваш программист или ваш инструмент.

• Доступ выдаётся и отзывается на стороне прав, а не отправкой кому-то пароля
• Объём определяем прямо: что уходит наружу, а что остаётся внутри
• К доступу прилагается документация, потому что интерфейс без описания — доступ только на бумаге

Что входит

Три элемента; о втором решаете вы, а не мы:

• Доступ к данным системы и к её действиям
• Права: кто, к чему и на какой срок
• Документация, описывающая, как этим пользоваться

Сроки

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

Стоимость

Программный доступ не стоит рядом с системой как отдельный договор — он её часть и заканчивается вместе с ней. Значит у него нет ни своего прайса, ни своего срока расторжения. Включать ли его вообще и насколько широко, определяют при настройке, вместе с остальными правами.

Если на вашей стороне нужна отдельная интеграционная работа — связка с системой, которую мы ещё не поддерживаем, — это отдельная услуга со своей ценой и своей статьёй: «Интеграции API».

Что вы получаете

Данные, которые не заканчиваются на нашем экране. Руководство может втянуть их в собственную сводку, сеть — сложить несколько локаций, а ваш программист — дописать инструмент, которого у нас нет. Заодно одна защита: раз доступ выдаётся отдельно, его можно отозвать, ничего не меняя в самой системе.

Как посчитать реальную нагрузку, прежде чем задавать лимиты доступа

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

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

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

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

Выбор зависит от того, как часто вам нужны данные и кто их принимает на другой стороне.

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

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

Когда программный доступ не окупается

Четыре ситуации, в которых стоит выбрать что-то другое:

• Никто с вашей стороны не программирует и не заказывает это на постоянной основе — доступ без того, кто им пользуется, остаётся ключом, который никто не берёт
• Потребность разовая, например одноразовая выгрузка для аудита — проще и дешевле ручной экспорт
• Достаточно смотреть на данные время от времени, без необходимости соединять их с другим инструментом — готовая панель в системе делает то же самое дешевле
• Речь на самом деле о соединении с конкретной другой системой, а не о сыром доступе к данным — это услуга «Интеграции», а не эта

В этом последнем случае разница не косметическая: доступ даёт сырые данные и документацию, интеграция строит готовое соединение между двумя конкретными системами.

Что нам нужно с вашей стороны, чтобы доступ имел смысл

Доступ без плана, для чего он нужен, — это просто ключ, лежащий в ящике стола.

• Технический человек — программист, интегратор или ваш инструмент — который реально будет пользоваться доступом
• Чёткий объём: какие данные и какие действия должны выходить наружу, а какие должны остаться внутри
• Решение, кто с вашей стороны выдаёт и отзывает права доступа, когда меняется состав команды

Без этого последнего решения доступ остаётся привязанным к одному человеку на постоянной основе — а это проблема, когда этот человек уходит из компании.

Как проверить эффект через месяц без нашего отчёта

Три вещи видны на стороне вашего инструмента, без входа в какой-либо наш сервис.

• Приходят ли запросы вообще — это видно в логах вашего инструмента или интегратора
• Достаточно ли документации, чтобы кто-то новый, кто никогда с ней не работал, запустил соединение самостоятельно
• Действительно ли отзыв доступа у одного человека мгновенно обрывает соединение, а не через несколько дней

Этот последний тест стоит провести один раз, осознанно, — это более простой способ проверить безопасность, чем читать договор.

Чего доступ к API не делает

Доступ даёт данные и права, но не пишет за вас инструмент, который ими пользуется — сам инструмент кто-то должен построить: ваш программист или мы, и тогда это уже работа, которую надо планировать, а не переключатель, который надо включить.

Мы также не обещаем конкретного времени ответа или непрерывной доступности — это не сервисный договор с гарантированным SLA, а доступ в рамках системы, которой вы пользуетесь каждый день. И он не заменяет стыковку систем: если вам нужно готовое, постоянное соединение с конкретной чужой системой, этим занимается слой интеграций — рядом, в той же AURA.

Самая частая ошибка при использовании доступа к API

Общий пароль вместо отдельных прав. Кто-то делится одним ключом доступа со всей командой, потому что так быстрее, — а потом никто не знает, какой инструмент им пользуется, и отзыв ключа у одного человека означает отключение всех сразу.

Цена этой ошибки становится очевидной только при расставании с сотрудником или при сбое: нужно отключить всё и запускать заново, вместо того чтобы просто отозвать доступ у одного человека. Поэтому права мы выдаём поштучно, а не одним общим ключом на всех.

Чьи это данные и что происходит, когда меняется само API

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

• Доступ выдаётся и отзывается на уровне прав, без изменения чего-либо в самой системе — отзыв доступа у одного человека или у всего инструмента не удаляет данные
• При расставании с AURA программный доступ заканчивается вместе с остальной системой, на тех же условиях, что и всё прочее — это не отдельный договор, который нужно расторгать отдельно
• Если мы сами меняем форму данных или способ их получения, мы делаем это как смену версии, а не тихую перезапись того, что уже работает, — старые инструменты не должны отключаться в один день без предупреждения

Обратная ситуация — когда ваш инструмент зависит от чужого API, а не от нашего, — несёт тот же риск: другая сторона может изменить свой интерфейс, ни у кого не спросив. Поэтому документация и логи — часть доступа, а не дополнение: чтобы такое изменение было видно сразу, а не через неделю тишины.