API - согласованный способ одной программы запросить данные или действие у другой. Благодаря ему сайт передаёт заявку в CRM, платёжный сервис сообщает результат, а мобильное приложение показывает баланс. Полезный API - это не просто набор адресов. Это договорённость о структуре данных, правах доступа, ошибках и изменениях.
Исходите из реальных действий
Начните с событий и записей, которые нужны интеграции. Дайте операциям понятные имена и возвращайте клиенту только необходимые данные. Опишите допустимый ввод, возможные ответы и ошибки. Документация и примеры должны соответствовать работающей версии сервиса, а не старой идеальной схеме.
Безопасность - часть договора
Проверяйте, кто отправил запрос, и разрешено ли ему конкретное действие с конкретной записью. Одной общей роли пользователя недостаточно. Ограничивайте частоту запросов и проверяйте все входные данные. Секретные токены держите на доверенном сервере, а изменения денег, прав и клиентских данных записывайте в журнал.
Учитывайте ненадёжную сеть
Запрос может завершиться по тайм-ауту уже после того, как другой сервис выполнил действие. Важные операции записи должны быть идемпотентными: повтор не должен создавать второй заказ или платёж. Задайте тайм-ауты и понятные правила повторения. Для событийных интеграций сохраняйте попытки доставки и предусмотрите повтор неудачных событий.
Планируйте изменения
Клиенты и серверы редко обновляются одновременно. По возможности вносите совместимые изменения, а несовместимые - выпускайте в новой версии API. Следите, кто ещё использует старое поведение. Хорошо поддерживаемый API позволяет развивать продукт без хрупких индивидуальных исправлений для каждой интеграции.
