Страница таблицы

Здесь собраны запросы, которые одинаково работают с любой таблицей: получить поля, прочитать список строк или одну строку, создать, обновить, переместить и удалить строку. Настоящие названия полей и ID берите в документации API своей базы: там у каждой таблицы свой пункт в меню.

В примерах ниже {table_id} это ID таблицы, а {row_id} это ID строки. Каждый запрос передаёт токен в заголовке Authorization: Token YOUR_DATABASE_TOKEN и выполняется по HTTPS. Где взять токен: Получение API-токена.

Поля

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

Частые случаи:

текст: однострочное значение;
выбор одного варианта: целое число или текст (ID варианта или его значение); null снимает выбор; если передан текст, берётся первый подходящий вариант;
дата: дата и время в формате ISO;
связь с другой таблицей: массив ID строк или значений основного поля; при обновлении передавайте все связи сразу, пустой массив удаляет все связи; строка с именами через запятую превращается в массив; можно передать и один ID;
файл: массив объектов, в которых есть как минимум имя файла; подойдёт и список имён через запятую, и ответ загрузки файла;
поле только для чтения, связанное с подстановкой: массив значений и ID строк, его нельзя менять запросом.

Список полей

Список полей доступен, если у токена есть право на чтение, создание или обновление.

curl \
-X GET \
-H "Authorization: Token YOUR_DATABASE_TOKEN" \
"https://table.nodul.ru/api/database/fields/table/{table_id}/"

В ответе у поля есть как минимум:

Свойство	Что это
`id`	Первичный ключ. С префиксом `field_` это имя столбца, например `field_1`.
`name`	Название поля.
`table_id`	ID таблицы.
`order`	Порядок. У первого поля `0`.
`primary`	Основное поле. Его нельзя удалить, значение должно описывать строку.
`type`	Тип поля.
`read_only`	Если `true`, значение ячейки нельзя изменить.
`description`	Описание поля.

Дополнительные свойства зависят от типа и в общем ответе могут отличаться.

Список строк

GET на эндпоинт строк возвращает страницу строк. По умолчанию это первая страница.

curl \
-X GET \
-H "Authorization: Token YOUR_DATABASE_TOKEN" \
"https://table.nodul.ru/api/database/rows/table/{table_id}/?user_field_names=true"

Ответ содержит count, next, previous и results. В results у строки есть id, order и значения полей.

Параметры запроса:

Параметр	Зачем
`page`	Номер страницы. По умолчанию `1`.
`size`	Сколько строк на странице. По умолчанию `100`.
`user_field_names`	Если значение `y`, `yes`, `true`, `t`, `on`, `1` или пустая строка, в ответе настоящие названия полей. Иначе ключи имеют вид `field_` и ID, например `field_1`. Тогда же `order_by`, `include` и `exclude` ждут названия, а не ID.
`search`	Оставляет строки, в данных которых есть этот текст. По умолчанию пустая строка.
`order_by`	Сортировка по полям через запятую. По умолчанию `id`. `+` или отсутствие знака: по возрастанию. `-`: по убыванию. Пример с названиями: `order_by=Name,-Status`. Если название начинается с `+` или `-`, добавьте ещё один знак, например `+-Name`. Название с запятой берите в кавычки. Кавычку внутри названия экранируйте `\`. Без `user_field_names` указывайте `field_1,-field_2`.
`filters`	JSON-дерево фильтров. Если параметр передан, `filter__{field}__{filter}` и `filter_type` игнорируются. Подробнее на странице Фильтры.
`filter__{field}__{filter}`	Короткий фильтр. Пример: `filter__Name__equal=test`. Если поля с таким названием нет, поиск идёт по `field_id`. Без `user_field_names`: `filter__field_1__equal=test`.
`filter_type`	`AND` (по умолчанию) или `OR`. Имеет смысл, когда коротких фильтров два или больше.
`include`	Какие поля вернуть. По умолчанию все. Список через запятую: названий или `field_1,field_2`.
`exclude`	Какие поля убрать из ответа. Тот же формат, что у `include`.
`view_id`	ID представления. К запросу добавятся его фильтры и сортировка. ID виден в контекстном меню представления: число в скобках после названия. Если задан `order_by`, сортировка представления не применяется. Короткий `filter__` применяется вместе с фильтрами представления.
`{link_row_field}__join`	Значения полей связанной таблицы. Имя параметра: название поля связи и суффикс `__join`. Значение: список полей связанной таблицы через запятую. Поле связи из связанной таблицы так получить нельзя.

Получить строку

Возвращает одну строку по её ID.

curl \
-X GET \
-H "Authorization: Token YOUR_DATABASE_TOKEN" \
"https://table.nodul.ru/api/database/rows/table/{table_id}/{row_id}/?user_field_names=true"

row_id в пути: какую строку получить. Необязательный параметр user_field_names работает так же, как в списке строк.

Создать строку

curl \
-X POST \
-H "Authorization: Token YOUR_DATABASE_TOKEN" \
-H "Content-Type: application/json" \
"https://table.nodul.ru/api/database/rows/table/{table_id}/?user_field_names=true" \
--data '{
  "Name": "string"
}'

Необязательные параметры запроса: user_field_names (как выше), before (ID строки, перед которой вставить новую), send_webhook_events.

send_webhook_events запускает вебхуки после операции, если значение y, yes, true, t, on, 1 или пустая строка. По умолчанию вебхуки отправляются.

В теле передавайте только те поля, которые нужно заполнить. Имена ключей зависят от user_field_names.

Обновить строку

curl \
-X PATCH \
-H "Authorization: Token YOUR_DATABASE_TOKEN" \
-H "Content-Type: application/json" \
"https://table.nodul.ru/api/database/rows/table/{table_id}/{row_id}/?user_field_names=true" \
--data '{
  "Name": "string"
}'

row_id в пути: какую строку обновить. Параметры запроса: user_field_names и send_webhook_events.

Для поля связи при каждом обновлении передавайте полный список ID. Пустой массив снимет все связи.

Переместить строку

curl \
-X PATCH \
-H "Authorization: Token YOUR_DATABASE_TOKEN" \
"https://table.nodul.ru/api/database/rows/table/{table_id}/{row_id}/move/?user_field_names=true"

before_id ставит строку перед строкой с этим ID. Если before_id не передан, строка уходит в конец. Параметр send_webhook_events работает так же, как при создании.

Удалить строку

curl \
-X DELETE \
-H "Authorization: Token YOUR_DATABASE_TOKEN" \
"https://table.nodul.ru/api/database/rows/table/{table_id}/{row_id}/"

send_webhook_events необязателен и по умолчанию включён.