С выходом SeaTable v5.3 доступ к API SeaTable будет осуществляться только через новый API-шлюз. Прямой доступ к прежним конечным точкам dtable-db и dtable-server будет полностью удален.

Уже объявив об этом важном изменении на форуме , в этой статье мы расскажем о предпосылках перехода, конкретных преимуществах и наиболее важных моментах, которые разработчики должны теперь иметь в виду.

Статья предназначена в первую очередь для разработчиков, которые создали свои собственные решения на основе API SeaTable, а также для технически заинтересованных лиц, которые хотели бы узнать больше об архитектуре SeaTable.

Для пользователей, которые работают исключительно в веб-интерфейсе или используют интеграции через n8n , Zapier или Make.com , переход будет интересен, но не актуален на практике.

В SeaTable доступ к данным SeaTable осуществляется через два разных компонента:

  • dtable-server: Представляет содержимое базы в виде JSON, создает табличное представление и обеспечивает совместную работу в режиме реального времени.
  • dtable-db: Предоставляет SQL-подобный язык запросов и служит интерфейсом к бэкенду больших данных.

Соответственно, существовало две структуры API: например, строки таблицы выводились через /dtable-server/api/v1/{base_uuid}/rows/, а SQL-запросы выполнялись через /dtable-db/api/v1/query/{base_uuid}/. Для обоих API можно было установить индивидуальные лимиты; централизованного, общекомандного лимита ранее не существовало.

Наш детальный анализ использования API показывает четкую картину: подавляющее большинство пользователей SeaTable либо работают исключительно в веб-интерфейсе, либо используют API лишь от случая к случаю. В то же время, есть пользователи, которые интенсивно используют API. SeaTable Cloud обрабатывает до полумиллиона API-запросов каждый день - и более 70% этих внешних API-запросов поступает всего от 20 баз или десяти наиболее активных команд.

Мы также видим, что многие из этих запросов поступают от пользовательских интеграций или автоматизаций, которые не запрограммированы оптимальным образом. Это означает, что извлекаются большие объемы данных, многие запросы повторяются без необходимости, а эффективные стратегии запросов или кэширования используются редко. На практике это приводит к тому, что отдельные команды генерируют десятки тысяч запросов в день - часто для чтения и записи данных, как в классической базе данных SQL.

Это серьезная проблема для публичного SaaS-продукта, такого как SeaTable Cloud. Инфраструктура должна быть производительной и стабильной для всех. В то же время, нагрузка, вызванная интенсивным использованием API, должна быть смягчена. Если возникают пики нагрузки, это может повлиять на производительность для всех пользователей - например, за счет увеличения времени загрузки или задержки отклика API. Без прозрачности и целенаправленного контроля за использованием API практически невозможно гарантировать быстрый и стабильный пользовательский опыт для всех команд.

До версии 5.3 API SeaTable имел только относительно высокие минутные лимиты и умеренные часовые или дневные лимиты - каждый на базу и отдельно для dtable-server и dtable-db. Это означало, что лимиты можно было легко обойти, а централизованный контроль был практически невозможен.

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

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

Чтобы удовлетворить растущие требования к стабильности и прозрачности и в то же время иметь возможность лучше контролировать растущую сложность использования API, мы решили внедрить централизованный интерфейс с новым API-шлюзом, который предлагает множество преимуществ для всех групп пользователей:

  • Централизованная точка входа: В будущем все запросы к API будут проходить через шлюз, который действует как обратный прокси.
  • Гармонизация лимитов: Теперь существует центральный минутный и месячный лимит на команду, в зависимости от размера команды и подписки.
  • Прозрачность: Текущий расход всегда виден в веб-интерфейсе. Кроме того, заголовки x-ratelimit в API возвращают текущие значения.
  • Производительность: Повторяющиеся запросы могут быть получены из кэша, что снижает нагрузку на внутренние системы.

В будущем каждый запрос к API SeaTable всегда будет сначала проходить через сервер caddy, что гарантирует безопасное соединение. Затем за дело берется API-шлюз: он проверяет лимиты, создает журналы и отвечает на повторяющиеся запросы непосредственно из кэша. Только при необходимости запрос передается внутренним службам SeaTable (dtable-db или dtable-server). Таким образом, API остается быстрым, безопасным и справедливым для всех команд.

Техническая настройка шлюза API

  • Старые конечные точки dtable-db и dtable-server больше не поддерживаются, начиная с версии 5.3. Запросы к этим конечным точкам приводят к соответствующим сообщениям.
  • Индивидуальные решения и интеграции должны быть переведены на новые конечные точки API-шлюза. Документацию по этому вопросу можно найти по адресу api.seatable.com .
  • Стандартные интеграции (n8n, Zapier, Make.com), а также внутренние скрипты в SeaTable уже были переведены на новые конечные точки и продолжают работать без адаптации.

В будущем только два ограничения будут регулировать доступ к базе SeaTable:

  • Минутный лимит: Защищает от кратковременных пиков нагрузки и злоупотреблений.
  • Месячный лимит: Зависит от размера команды и подписки. Более крупные команды получают пропорционально больше API-запросов в месяц.

Использование и оставшиеся квоты можно в любой момент просмотреть в веб-интерфейсе и через “заголовки API”. Если месячный лимит превышен, подписка команды может быть продлена напрямую, чтобы запросы могли быть сделаны снова немедленно.

Вот пример возврата x-ratelimit-header в командной строке:

x-powered-by: SeaTable-Api-Gateway
x-ratelimit-limit: 200
x-ratelimit-remaining: 199
x-ratelimit-reset: 1748424867

Как видно из примера, API SeaTable возвращает так называемые Rate-Limit-Headers при каждом вызове.

В этих заголовках содержится информация о том, сколько запросов API Вам разрешено делать в минуту (x-ratelimit-limit), сколько их осталось в текущем временном окне (x-ratelimit-remaining) и когда лимит будет сброшен (x-ratelimit-reset, в виде временной метки Unix).

По техническим причинам API всегда отображает здесь минутный лимит, поскольку его можно проверить быстро и без трудоемких запросов к базе данных. Однако, если месячный лимит Вашей команды достигнут, API возвращает значение 0 для ‘x-ratelimit-remaining’ и время следующего месячного старта при сбросе. Такое поведение было реализовано намеренно, чтобы избежать лишних запросов к базе данных для каждого запроса и сохранить высокую производительность.

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

Благодаря кэшированию в шлюзе, частые запросы на чтение выполняются быстрее, не нагружая каждый раз бэкэнд. В то же время, новая модель позволяет командам с очень высокими требованиями к API в будущем платить за их использование отдельно - что позволяет сохранить стабильные расходы для всех остальных команд.

С версией 5.3 SeaTable устанавливает курс на перспективное, справедливое и эффективное использование API. Разработчикам придется перевести свои решения на новые конечные точки, но они выиграют от большей прозрачности, лучшей производительности и четких правил.

TAGS: