Подключение внешней базы данных по API с помощью коннектора

Как это работает

При создании таблицы нужно указать “Импорт таблицы по API”.

В настройках указать URL-ендпоинт коннектора, который все запросы будет обрабатывать, и при необходимости, HTTP-заголовки. Их можно не указывать, они не обязательные. Ендпоинт должен работать только с одной таблицей. Если нужно подключить несколько таблиц, значит нужно создать несколько ендпоинтов с разными URL, и подключить их.

Формат запроса

Обращение к ендпоинту происходит методом POST. Формат запроса application/json.
Пример, в котором запрашивается просто первые 10 строк таблицы, без фильтров и сортировки:

{
  "properties": {},
  "sort": [],
  "limit": 10,
  "skip": 0
}

Более сложный пример, с фильтрами и сортировкой, и запросом вторых 10 строк таблицы:

{
  "properties": {
    "name": "Евгений"
  },
  "sort": [
    {
      "column": "age",
      "direction": "desc"
    },
    {
      "column": "rating",
      "direction": "asc"
    }
  ],
  "limit": 10,
  "skip": 10
}

Фильтры (properties)

properties - это ключ-значение, в котором как ключи так и значения всегда являются строками. Ключи и значения могут быть произвольными строками.
При подключении таблицы к шаблонной странице Creatium использует именно это поле, чтобы получить данные одной конкретной строки.

Сортировка (sort)

Объект, в котором в порядке важности перечислены поля, по которым нужно отсортировать, и направление сортировки (desc или asc).

Количество (limit)

Просто число. Если передается 0, значит количество не задано, и вывести нужно вообще все (для карты сайта, например).

Пропуск (skip)

Тоже просто число, которое используется для пагинации. Аналог OFFSET из MySQL.

Формат ответа

В ответе обязательно нужно прислать columns (список колонок), rows (найденные строки) и totalCount (общее количество найденных строк).

{
  "columns": [
    {
      "id": "name",
      "name": "Имя",
      "type": "string"
    },
    {
      "id": "email",
      "name": "Почта",
      "type": "string"
    },
    {
      "id": "age",
      "name": "Возраст",
      "type": "number"
    },
    {
      "id": "photo",
      "name": "Фото",
      "type": "string"
    }
  ],
  "rows": [
    {
      "name": "Иван Иванов",
      "email": "ivan@example.com",
      "age": 37,
      "photo": "https://.../001_1.jpg"
    },
    {
      "name": "Петр Петров",
      "email": "petr@example.com",
      "age": 22,
      "photo": "https://.../001_2.jpg"
    }
  ],
  "totalCount": 122
}

Типы данных

Сейчас поддерживается только 2 типа данных: string и number.

Пагинация

Если база данных не поддерживает ни в каком виде аналог totalCount, можно прибегнуть к следующему варианту. Если количество записей в результате равняется limit, тогда считаем, что totalCount равен *`offset + limit 2`**, то есть делаем вид, будто есть еще одна страница, и тогда в пагинации будет доступен переход вперед. С первой страницы на вторую, со второй на третью, с третьей на четвертую, и тд, по одной странице за один раз.

Коды ошибок

Решение о том, какую ошибку выкидывать, и выкидывать ли ее вообще, остается на стороне API. То есть мы можем порекомендовать, что в случае сортировки по несуществующему полю, стоит бросать ошибку 422, но автор API может пренебречь этим. Тем не менее, мы должны быть готовы к следующим кодам ошибок:
400 - Bad Request
Неправильный запрос. Например, не удалось считать параметры.
401 - Unauthorized
Не удалось авторизоваться по указанным реквизитам, или реквизиты вообще не указаны.
403 - Forbidden
Нет доступа к этому ендпоинту. Например, реквизиты авторизации верны, но у пользователя недостаточно прав.
404 - Not Found
Ендпоинт не найден.
408 - Request Timeout
Таймаут. Например, из базы вернулся, и эта ошибка нам передается.
413 - Request Entity Too Large
Слишком большой запрос. Пока не представляю, что это может быть, но например в properties передана строка размером в 10 мб.
422 - Invalid Request
Ошибка в запросе, или его не получается выполнить. Примером могут быть неправильные properties, сортировка по несуществующему полю и т.д.
`5` - Любые ошибки сервера**
Значит неизвестно что случилось, просто тоже нужно не забывать про эти коды, которые часто возникают.

Пример коннектора 1: Таблица с курсом валют

Ссылка: https://www.napkin.io/n/86197c8ee82940c5
Этот код можно “форкнуть” прямо в сервисе Napkin и подключить к своему сайту.
Это максимально простой пример. В нем мы берем JSON из https://www.cbr-xml-daily.ru/daily_json.js, применяем к нему properties, sort, limit, skip и возвращаем в нужном формате.
Наглядно демонстрирует, что ожидается от коннектора, как он должен преобразовывать данные.

Пример коннектора 2: Подключение MySQL

Ссылка: https://www.napkin.io/n/a3ae44a1ba584370
Этот коде тоже можно “форкнуть” прямо в сервисе Napkin и подключить к своему сайту.
Это более сложный пример, в котором все разнообразие типов поле MySQL приводится к двум поддерживаемым: string и number.
Параметры properties, sort, limit, skip преобразуются в SQL-запрос, а для того, чтобы посчитать totalCount используется связка SQL_CALC_FOUND_ROWS и FOUND_ROWS().
При подключении к Creatium нужно в ссылке указывать параметр ?table=... с названием таблицы, к которой нужно подключиться.

🔥Кейс подключения MySQL к Creatium от пользователя:
https://vine-acapella-902.notion.site/Creatium-6e63b44805d24e17995d0fd9b53216fa

Возможные проблемы

В редакторе все работает корректно, а в публикации возвращает 404

Скорее всего вы не обрабатываете параметр properties. Именно в этом параметре указывается идентификатор записи, которую Creatium ожидает получить.

Если value пустое, то ничего не найдено

Решается добавлением кода в обработчик:

const whereParts = [];

for (const key in query.properties) {
    const value = query.properties[key];

    if (value !== undefined && value !== null && value !== '') {
        whereParts.push(`${cleanEntityName(key)} = ?`);
        placeholders.push(value);
    }
}