Определите операцию VPN до того, как сравнивать API

Страница продукта говорит, что у него есть API, а встреча по интеграции застревает на втором вопросе. Какая операция, над каким объектом, кем вызывается и что считается успехом? Ответы на эти четыре вопроса до сравнения продуктов обычно отсеивают половину кандидатов. Это же превращает оставшееся сравнение в то, что может решить тест.

Замените «есть API» одной операцией

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

Запишите операцию как предложение, прежде чем смотреть документацию.

Запуск локального подключения — действие на стороне клиента, перед которым сидит пользователь. Выдача профиля устройства — действие по подготовке, за которым стоит инвентарь. Отключение доступа пользователя — административное действие со следом аудита. Эти три обычно живут в разных компонентах, принадлежат разным командам и имеют разные полномочия.

Четыре поля, которые делают контракт проверяемым

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

Таблица — это весь рабочий лист:

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

Если двум операциям нужны разные вызывающие, это две интеграции. Объединение их в одну служебную учётную запись обычно означает выдачу больше полномочий, чем нужно любой из них.

Сопоставьте интерфейс с тем слоем, которому он действительно принадлежит

Общественный интерфейс управления OpenVPN общается с демоном через TCP или сокет Unix. Его команды включают наблюдение за состоянием и сигналы демону.

Это делает его каналом управления демоном, а не размещённым API подписки или службой регистрации пользователей. Внимательное чтение его документации избавляет от сборки поверх слоя, который не владеет объектом.

Документация также говорит, что протокол не несёт собственного шифрования. Кто может добраться до сокета, тот может управлять демоном, поэтому относитесь к нему как к чувствительному управлению, а не как к потоку метрик. Привяжите его к loopback или сокету Unix и поставьте за ограниченную схему, если удалённому вызывающему это нужно. Выставление его в интернет ради удобства превращает канал управления в инцидент.

Опишите поведение после вызова

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

Решите, что делает вызывающий, если ответ потерян. Слепо повторять создание или переподключение — не то же самое, что проверять, подействовал ли первый запрос.

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

Проверьте контракт пилотом

Небольшой одобренный пилот должен охватывать успех, отказ, прерывание и повтор, а затем операцию приложения, которую следует разрешить или запретить.

Для интерфейса уровня демона две команды упражняют наблюдение и сигнал:

echo state | nc -w 2 127.0.0.1 7505
echo signal SIGTERM | nc -w 2 127.0.0.1 7505

Выдавайте только те полномочия, которые требует операция. Держите секреты вне обычных журналов и записывайте достаточно приватных деталей, чтобы сказать, какая цель была затронута и чем всё закончилось.

Запишите путь восстановления на случай, когда сам API управления недоступен. Выбирайте интерфейс, который владеет объектом и его жизненным циклом; заявления об автоматизации на странице продукта не заменяют этого.