REST API базы данных Baserow: эндпоинты и примеры запросов

Для каждой базы данных Baserow автоматически генерирует REST API с документацией по её собственной схеме - через него можно читать и изменять строки программно, аутентифицируясь database-токеном, без обращения к веб-интерфейсу; ниже показано, где найти эту документацию, какие эндпоинты доступны и как форматировать значения для разных типов полей.

Обзор

API-first подход Baserow позволяет интегрировать базы данных с любым приложением, автоматизировать рабочие процессы и строить собственные решения без привязки к конкретному поставщику. REST API следует стандартным конвенциям, использует JSON для обмена данными и возвращает стандартные HTTP-коды состояния для понятной обработки ошибок.

Аутентификация выполняется через database-токены с гранулярными правами вплоть до уровня таблицы - можно управлять доступом на создание, чтение, обновление и удаление отдельно для каждого токена, что обеспечивает безопасную интеграцию с внешними приложениями.

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

Доступ к документации API базы данных

1. Нажмите значок ⋮ рядом с именем базы данных.
2. Выберите View API Docs в меню.
3. Просмотрите автогенерируемые эндпоинты, соответствующие вашей схеме.
4. Выполните первый запрос к API.

curl \
-X GET \
-H "Authorization: Token YOUR_DATABASE_TOKEN" \
"https://api.baserow.io/api/database/fields/table/TABLE_ID/"

Как получить database-токен для рабочего пространства - в статье «Персональные API-токены Baserow» .

Основные конечные точки API

Проверяйте эндпоинты инструментами вроде curl или Postman.

Анатомия конечной точки Baserow API

https://api.baserow.io/api/database/rows/table/TABLE_ID/?user_field_names=true

Аутентификация

Baserow использует токенную аутентификацию для доступа к API. Токены привязаны к конкретным базам данных и таблицам, а права на создание, чтение, обновление и удаление настраиваются отдельно для каждой таблицы - используйте права только на нужные таблицы, а не полный доступ ко всей базе.

Все запросы к API должны выполняться по HTTPS и включать database-токен в заголовке Authorization.

Authorization: Token YOUR_DATABASE_TOKEN

Токен можно отозвать в любой момент в настройках аккаунта.

Храните токены в переменных окружения, а не в коде, и регулярно их обновляйте.

Ограничения частоты запросов

Облачная версия: в Baserow Cloud действует лимит в 10 одновременных запросов к API. Ограничение подчиняется политике добросовестного использования и может быть снижено при влиянии на общую производительность.

Self-hosted: ограничений частоты запросов нет.

Работа с типами полей

Разные типы полей требуют определённого формата данных при создании или обновлении строк.

Текстовые и числовые поля

{
  "Name": "John Doe",
  "Age": 25,
  "Email": "john@example.com"
}

Поля выбора

Указывайте либо названия опций, либо их внутренние идентификаторы.

Одиночный выбор. Принимает число или текст, представляющий идентификатор или значение выбранной опции. Значение null означает, что ничего не выбрано. Если передан текст, выбирается первая совпавшая опция.

{
    "Timezone": {
        "id": 1,
        "value": "Option",
        "color": "light-blue"
    }
}

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

{
    "Team": [
        {
            "id": 1,
            "value": "Option",
            "color": "light-blue"
        }
    ]
}

Поля связи с таблицей

Принимает массив, содержащий идентификаторы или значения первичного поля связанных строк из указанной таблицы. При каждом обновлении связей нужно передавать все идентификаторы целиком - пустой массив удалит все связи. Если вместо идентификатора передан текст, выполняется поиск строки с совпадающим значением первичного поля; при нескольких совпадениях выбирается первая строка по порядку в таблице. Можно передать строку с названиями через запятую, а также идентификатор строки без обёртки в объект.

{
     "Customer": [
        {
            "id": 0,
            "value": "string"
        }
    ]
}

Поля даты и логические поля

{
  "Created": "2024-01-15T10:30:00Z",
  "IsActive": true
}

Обработка ошибок

Baserow использует стандартные HTTP-коды состояния с подробными сообщениями об ошибках - реализуйте в приложении корректную обработку ошибок и логику повторных попыток.

Основные коды состояния:

Формат ответа с ошибкой:

{
    "error": "ERROR_NO_PERMISSION_TO_TABLE",
    "description": "The token does not have permissions to the table."
}

Фильтрация и пагинация

Параметры строки запроса для получения списка строк.

Фильтрация:

• filters - JSON-объект с условиями фильтра; строки можно фильтровать теми же фильтрами, что доступны в представлениях.
• filter_type - «AND» или «OR» для нескольких фильтров; работает только при двух и более фильтрах.
• search - полнотекстовый поиск по всем полям; возвращаются только строки, данные которых соответствуют запросу.

Сортировка:

• order_by - имя поля для сортировки; по умолчанию или с префиксом «+» сортировка идёт по возрастанию (A-Z), а с префиксом «-» - по убыванию (Z-A).

Пагинация. Используйте пагинацию для больших наборов данных.

• size - количество строк на странице (по умолчанию 100, максимум 200).
• page - номер страницы (начиная с 1).

GET /api/database/rows/table/123/?filters={"Status":"Active"}&order_by=-Created&size=50&page=2

Спецификация OpenAPI

Спецификация OpenAPI содержит подробные описания параметров, примеры запросов и ответов - её можно импортировать в инструменты вроде Postman или Insomnia.

Полная спецификация API доступна здесь:

• Интерактивная документация: https://api.baserow.io/api/redoc/
• JSON-схема: https://api.baserow.io/api/schema.json

Интеграция с вебхуками

Совмещайте вызовы API с вебхуками для синхронизации данных в реальном времени. Вебхуки уведомляют приложение об изменении данных, а вызовы API позволяют запрашивать и обновлять данные программно - вместе они образуют двунаправленный сценарий интеграции. Подробнее о механике - в статье «Вебхуки Baserow» .

Часто задаваемые вопросы

Как найти идентификаторы таблицы и базы данных? Они видны в адресной строке браузера при просмотре таблицы, а также их можно получить через эндпоинт списка таблиц. Подробнее - в статье «Идентификаторы базы данных и таблицы Baserow» .

Можно ли использовать API без создания аккаунта? Нет, все эндпоинты API требуют аутентификации database-токеном, а для этого нужен аккаунт Baserow и доступ к соответствующей базе данных.

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

Как обрабатывать ограничения частоты запросов? Для облачной версии реализуйте логику повторных попыток с экспоненциальной задержкой; у self-hosted инсталляций ограничений нет. Следите за заголовками ответа, отражающими состояние лимита.

Можно ли создавать или обновлять несколько строк одним запросом? Стандартный API создаёт или обновляет одну строку за запрос. Для массовых операций выполняйте несколько последовательных вызовов API.

Как отладить проблемы с аутентификацией API? Проверьте, что токен указан верно, обладает нужными правами на таблицу и передан в заголовке Authorization в формате Token YOUR_DATABASE_TOKEN; также убедитесь, что идентификаторы базы данных и таблицы указаны правильно.

Далее - статья «Идентификаторы базы данных и таблицы Baserow» : как найти database_id и table_id для подстановки в запросы к REST API, описанному выше.