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

> Каждая база данных Baserow получает автогенерируемую документацию REST API: разбираем эндпоинты, токенную аутентификацию и форматы значений для типов полей.

Source: https://opennix.org/docs/baserow/webhook-api/database-api/


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

## Обзор

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

Аутентификация выполняется через [database-токены](/docs/baserow/webhook-api/personal-api-tokens/) с гранулярными правами вплоть до уровня таблицы - можно управлять доступом на создание, чтение, обновление и удаление отдельно для каждого токена, что обеспечивает безопасную интеграцию с внешними приложениями.

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

![Документация REST API базы данных Baserow с эндпоинтом Get row, примерами запроса и ответа](/images/baserow/webhook-api/database-api-overview.jpg)

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

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

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

Как получить database-токен для рабочего пространства - в статье [«Персональные API-токены Baserow»](/docs/baserow/webhook-api/personal-api-tokens/).

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

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

| Операция | Метод | Эндпоинт | Описание |
|---|---|---|---|
| Список таблиц | `GET` | `/api/database/tables/all-tables/` | Все таблицы в рабочем пространстве |
| Список полей | `GET` | `/api/database/fields/table/{table_id}/` | Схема полей таблицы |
| Список строк | `GET` | `/api/database/rows/table/{table_id}/` | Все строки с фильтрацией и пагинацией |
| Получить строку | `GET` | `/api/database/rows/table/{table_id}/{row_id}/` | Конкретная строка по идентификатору |
| Создать строку | `POST` | `/api/database/rows/table/{table_id}/` | Добавить новую строку в таблицу |
| Обновить строку | `PATCH` | `/api/database/rows/table/{table_id}/{row_id}/` | Изменить существующую строку |
| Переместить строку | `PATCH` | `/api/database/rows/table/{table_id}/{row_id}/move/` | Изменить позицию строки |
| Удалить строку | `DELETE` | `/api/database/rows/table/{table_id}/{row_id}/` | Удалить строку из таблицы |

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

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

| Компонент | Описание | Пример |
|---|---|---|
| Базовый URL | Сервер API Baserow | `https://api.baserow.io` (облако), `https://your-domain.com` (self-hosted) |
| Путь API | Структура эндпоинта | `/api/database/rows/table/` |
| TABLE_ID | Уникальный идентификатор таблицы | `12345` |
| Параметры | Опции строки запроса | `?user_field_names=true` |

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

Baserow использует [токенную аутентификацию](/docs/baserow/webhook-api/personal-api-tokens/) для доступа к API. Токены привязаны к конкретным базам данных и таблицам, а права на создание, чтение, обновление и удаление настраиваются отдельно для каждой таблицы - используйте права только на нужные таблицы, а не полный доступ ко всей базе.

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

```
Authorization: Token YOUR_DATABASE_TOKEN
```

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

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

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

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

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

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

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

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

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

### Поля выбора

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

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

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

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

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

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

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

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

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

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

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

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

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

| Код ошибки | Название | Описание |
|---|---|---|
| 200 | Ok | Запрос выполнен успешно |
| 400 | Bad request | Запрос содержит недопустимые значения, или JSON не удалось разобрать |
| 401 | Unauthorized | Обращение к эндпоинту без действительного database-токена |
| 404 | Not found | Строка или таблица не найдена |
| 413 | Request Entity Too Large | Размер запроса превысил допустимый лимит |
| 500 | Internal Server Error | Сервер столкнулся с непредвиденным состоянием |
| 502 | Bad gateway | Baserow перезапускается, или произошёл непредвиденный сбой |
| 503 | Service unavailable | Сервер не успел обработать запрос вовремя |

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

```json
{
    "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).

```bash
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/](https://api.baserow.io/api/redoc/)
- **JSON-схема**: [https://api.baserow.io/api/schema.json](https://api.baserow.io/api/schema.json)

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

Совмещайте вызовы API с вебхуками для синхронизации данных в реальном времени. Вебхуки уведомляют приложение об изменении данных, а вызовы API позволяют запрашивать и обновлять данные программно - вместе они образуют двунаправленный сценарий интеграции. Подробнее о механике - в статье [«Вебхуки Baserow»](/docs/baserow/webhook-api/webhooks/).

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

**Как найти идентификаторы таблицы и базы данных?** Они видны в адресной строке браузера при просмотре таблицы, а также их можно получить через эндпоинт списка таблиц. Подробнее - в статье [«Идентификаторы базы данных и таблицы Baserow»](/docs/baserow/webhook-api/database-and-table-id/).

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

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

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

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

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

Далее - статья [«Идентификаторы базы данных и таблицы Baserow»](/docs/baserow/webhook-api/database-and-table-id/): как найти `database_id` и `table_id` для подстановки в запросы к REST API, описанному выше.