Опыт гуманитария — связываю нокодинговые БД и конструктор приложений по API

Описываю опыт связи QuintaDB и Adalo через API, поясняя, почему не стал делать это через Zapier.

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

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

Кому всё это не нужно, то переходите сразу к разделу «Описание кейса».

В первую очередь — не программистам и не специалистам в области IT) Это опыт гуманитария, описанный для других гуманитариев: тем, кто пилит свой стартап и пока без разработчика (допустим MVP), тем менеджерам или даже линейным специалистам, которые сами автоматизируют какие-то свои бизнес-процессы без привлечения специалистов из IT департаментов.

Главные герои, инструменты не требующий знаний языков программирования (зерокодинг, no-code):

• QuintaDB (ранее известная как mytaskhelper) — онлайн реляционная БД c широким бизнес функционалом.
• Adalo — конструктор мобильных приложений (типа Тильды, но для приложений).

Вскользь будут упомянуты: API, Zapier, Airtable, Glide, Figma, Staker.

Я продюсер. Специализация — производство медиа контента. В общем, гуманитарий, связанный с IT лишь для автоматизации продакшн процессов. Взялся за свой собственный проект — мобильное приложение для отображение досуговых мероприятий на карте. Я бы назвал его стартап, только он ещё далёк от смысла этого термина (круто стартующий) — это всё ещё просто венчурный проект (рискованный).

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

Figma - прекрасный инструмент разработки дизайна приложения и делает вполне кликабельный прототип, порой достаточный для MVP, но это лишь имитация, конечно. Есть два отличных инструмента, которые позволяют собрать функциональный прототип (а для небольших проектов так и вообще полноценное мобильное приложение, т.е. этих инструментов вполне хватит на всю жизнь проекта или задачи) без привлечения разработчиков — Adalo и Glide. Оба они прекрасны, но у Glide есть некоторые ограничения, которые для меня сейчас критичны:

• Glide пока работает только с самым простым видом БД — google sheets, т.е. может быть связан только с вашей гугловской таблицей.
• Glide пока не умеет публиковать ваше приложение в сторах (в AppStore и Google Play), только как адаптивная веб-страничка, которую можно сохранить иконкой на экран смартфона (формат PWA), далее полное ощущение самостоятельного мобильного приложения.

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

Для разработки онлайн БД без программирования тоже есть целый пул прекрасных решений — в мом случае, выбор у меня был между Airtable и QuintaDB. Airtable — очень симпатичное решение, с прекрасным дизайном, отличной юзабельностью ввода и работы с данными (т.е. ощущение работы с ним вполне аналогичные при работе с десктопным Exel или Google таблицами), но для меня в нём оказались критичным отсутствие следующих возможностей:

1. Отсутствие возможности создать в Airtable клиентского портала и личного кабинета пользователя. Пока это возможно лишь в связке c ещё каким-нибудь инструментом, типа Stacker, но это делает всё экономику прототипа слишком дорогой, а логику слишком громоздкой.

2. Существенно большая стоимость пользования — тарифы в AirTable выше тарифов в QuintaDB и существенно меньший функционал на бесплатном тарифе.

В самой же QuintaDB, помимо перечисленного, есть ещё одно важное и нынче очень редкое качество: это русскоязычный интерфейс и прекрасная русскоговорящая поддержка — очень дружественная и оперативная команда. Мой английский плох, я спасаюсь в переписке и различных манулаха вполне google translate, но когда начинаешь работать совсем с новой сущностью, это обстоятельство для меня становиться важным.

Вот, пожалуй, и всё по поводу контекста — думаю, что у многих ситуация похожая. Надеюсь, что всё это вводная вода не зря и пригодится ищущим решений своим задачам. Далее уже конкретно по кейсу.

Задача: связать Adalo с БД на QuintaDB по API.

Условие: Не использовать Zapier.

У QuintaDB есть свой zap (подготовленный блок интеграции) в Zapier — и это очень круто, но, к сожалению, это лишь ещё бета версия и она обладает важным ограничением — в Adalo zap передаёт только те записи, которые в самой QuintaDB создаются через функцию «Добавить запись» в соответствующей таблице. Если Вы в эту таблицу импортируете новые записи (через CSV или Excel), или даже создаёте новую запись путём клонирования существующей — zap не распознаёт такие записи как новые и не передаёт их в Adalo. UPD_2021-09-02 - полечили)

Но даже не это только критично (уверен, что команда QuintaDB скоро решит и эту задачу) — Zapier сам по себе дорогой сервис уже на более-менее приличных объёмах. Есть, кстати, хорошая и ему альтернатива — Integromat. И команда QuintaDB уже делает решение и для этого сервиса.

Главная засада в задаче для меня в том, что я сам гуманитарий и вот этот API — для меня это какой-то ужасный монстр. Это набор каких-то команд, которые мне совсем не понятны — ни в документации на QuintaDB, ни в форме связи на Adalo. Но оказалось, что всё не так страшно — синтаксис команд поддаётся логике, которую можно понять, таки, даже будучи лириком)

Поехали решать задачу)

Для подключения к внешней БД Adalo необходима информация, которую надо будет указать в соответствующей форме. Это:

1. URL адрес подключения к вашей БД по API.
2. Данные для авторизации этого подключения.
3. По необходимости, уточнения для действий с этой БД (для получения информации из БД или для отправления новой информации обратно в БД) — в нашем случае такая необходимость есть.

Важный нюанс. Два сервиса (Adalo и QuntaDB) разработаны, конечно, разными командами и есть отличие в логике приёма-передачи информации, т.е. в формировании данных для интеграции:

• Adalo - получает связь с БД через специальную форму, которая призвана упростить настройку это связи так, что бы «не быть программистом». Т.е. Adalo просит указать разные параметры в разных полях формы запроса.
• QuintaDB — настраивает связь с другими сервисами по API через специальные команды API, которые являются некоторым «предложением», где слова и смысловые связи есть набор данных собранных в последовательности и синтаксисе языка запросов API. Т.е. Quinta передаёт данные единой строчкой информации.

В общем, для того, что бы нам указать в форме Adalo всю необходимую информацию, нам надо прежде сформировать корректный запрос в Quinta, типа — "Как получить все записи из конкретной таблицы", а после его разложить на необходимые составляющие, которые мы и будем указывать в форме на Adalo — «API Base URL» и «Auth Setup».

Звучит так себе для лирика. Но как показал процесс, не так страшен чёрт, как его малюют)

Ок. Давайте прежде эту информацию из QuintaDB получим, попутно немного разобравшись с соответствующими запросами API.

Для описания этого кейса на сервисе QuintaDB создал проект «QuintaDB-&-Adalo» и в нём завёл простую табличку «Таблица мероприятий».

Переходим в раздел «Документация по API» по пути: Аккаунт\Поддержка\Разработчикам

Вот там гуманитария и ждёт самый треш!) Но не бойтесь — всё не так страшно.

И так, нам надо сформировать API запрос для нашей таблицы, что бы в Adalo прилетали все записи из неё — в нашем примере, весь набор мероприятий. Смотрим на быстрые ссылки оглавления документации по API на сайте QuintaDB. Похоже, что ссылка на «Получить все записи» это то, что нам надо.

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

• rest_api_key — это наш API ключ ко всем нашим проекта на QuintaDB, наш главный идентификатор для API.
• APP_ID — это уникальный код нашего проекта на QintaDB (кстати, в терминологии QuintaDB «проект» (который может состоять из суммы таблиц) называется «приложение», потому и в идентификаторе у нас «APP… » — просто запомните это).
  
• ENTITY_ID - это уникальный код нашей таблицы (в терминологии QuintaDB, часто «формой» называется ещё и конкретная таблица, а не только форма внесения данных в неё — тоже просто запомните это).
  
• page - это обязательный элемент запроса, он указывает, сколько страниц информации (записей) надо будет передать в другой сервис.

Начнём собирать эти данные.

1-1. rest_api_key (ключ API)

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

Ок. Получаем наш API key.
Путь: Аккаунт\Поддержка\Разработчикам\API ключи\Создать API ключ

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

1-2. APP_ID

APP_ID — это идентификатор созданного проекта «QiuntaDB-&-Adalo».

Что нам пишет QuintaDB по этому поводу — "Вы должны знать идентификатор базы. Вы можете найти APP_ID получив все базы данных."

Это значит, что бы узнать, какой у нашего проекта ID надо сделать специализированный запрос через браузер.

По ссылке мы видим инструкцию, которая гуманитария может поставить в тупик. Меня поставила) Я выпил и разобрался. В общем — всё не сложно, как оказалось.

Ответ здесь:

В адресной строке браузера к адресу сайта QuintaDb мы добавляем эту строчку и получаем ответ на наш вопрос. Т.е. адресная строка должна выглядеть так:

Результат ( в моём случае)

У меня на QuintaDB сейчас в работе 3 проекта, потому в результате показываются данные по нескольким проектам — по 2 строчки данных на каждый проект. В нашему случае — это 2-ая группа строчек, там мы видим название нашего проекта «QiuntaDB-&-Adalo» и его ID «ddSSkFW6zcI4ofnSoLW7e1»

Кстати, если в адресной строке в конце вместо JSON поставить XML, то результат будет более наглядным и структурным — ориентироваться в нём будет проще. Особенно, когда у Вас будет много данных (а такое будет).

Ок, мы получили APP_ID! Запишем его в нашем блокноте «APP_ID = "ddSSkFW6zcI4ofnSoLW7e1" (в моём случае, конечно).

1-3. entity_ID

Инструкция по API нам указывает — "Вы должны знать идентификатор формы. Вы можете найти entity_ID получив все формы."

Переходим и видим код запроса, который чуть сложнее, но уже не должен нас испугать:

/apps/ID/entities.json в полном варианте так:

В запрос для браузера, прежде чем его скопировать, нам надо вставить вместо «ID» уже известным нам на предыдущем шаге наш App-ID — «ddSSkFW6zcI4ofnSoLW7e1» (у Вас он свой).

В результате, полная адресная строка будет такой:

Ну и сразу заменим окончание на XML, что бы результат был более наглядным и удобным:

Ответ:

ID таблицы (form) в запросе есть — <id>aoWPRdShXiokzYlrldOSkG</id>, т.е. наш entity_ID = aoWPRdShXiokzYlrldOSkG Сохраним это значение в наш блокнот.

1-4. page

page - это обязательный элемент запроса, он указывает сколько страниц информации (записей) надо будет передать в другой сервис. На одной странице по умолчанию QuntaDB показывает 20 записей, т.е. если у вас записей, допустим 30, то page должен быть равен «2», если 50 — «3» и т.п. Я пробовал и «1» и «10» — разницы в Adalo не увидел — передаёт все записи одинаково). Но параметр этот должен быть и позже я покажу где.

Ок, эта часть данных у нас тоже теперь есть. Сохраните себе в блокнот — «page = 1» (как минимум).

Проверка

Итого, мы имеем необходимые нам для заполнения формы связи с внешней БД на Adalo все необходимые данные:

• rest_api_key — Ваш личный API ключ.
• APP_ID — Это ID нашего проекта — ddSSkFW6zcI4ofnSoLW7e1 (для данного кейса и для моей авторизации).
  
• entity_ID — Это ID нашей таблицы — aoWPRdShXiokzYlrldOSkG (для данного кейса и для моей авторизации).
  
• page — 1 — необходимый аргумент.

Теперь из части этих данных (2 и 3) нам надо собрать запрос для выгрузки всех наших мероприятий (записей) из таблицы «Таблица мероприятий».

В инструкции на задачу «Получить все записи» запрос описан так:

/apps/APP_ID/dtypes/entity/entity_ID.json

Прежде, чем переходить в форме настройки связи в Adalo, проверим корректность запроса через браузер.

Подставим известные нам уже значения и для удобства сменим окончание на xml — всё это добавим в адрес сайта QuintaDB

В браузере с результатом всё ок, вы видим записи нашей таблицы «Таблица мероприятий» — у нас там именно всего две записи.

Отлично, именно эти данные нам и надо передать в Adalo. Предлагаю вам также этот запрос сразу сохранить в ваш блокнот, только сменив окончание с «xml» на «json»

Можем приступать к настройке связи уже в Adalo через специальную форму.

ШАГ 1

Переходим в Adalo, в раздел Database\External Collections

Кликаем на «+ ADD collection»

Открывается форма настройка связи.

В поле 1 — пишем любой название для этой связи. Я напишу «QuintaDB — мероприятия».

В поле 2 — вставим наш запрос, который мы собрали на предыдущем шаге —

А вот теперь пришла пора указать наши данные авторизации, так как в строке запроса они не участвует (что, в общем, для безопасности очень даже не плохо).

В запросе мы использовали два наших идентификатора из 4х — APP_ID и entity_ID. Теперь мы используем 2-а оставшихся — rest_api_key и page.

Для этого добавим два этих аргумента последовательно через кнопку «+ADD ITEM», выбрав в модальном окне тип «Query Param»

Сначала добавим данные для авторизации — rest_api_key и кликнем «Done» (помните, что значение API ключа у Вас своё)

Потом аналогично добавим ещё один идентификатор для запроса — "page" со значением «1» и так же кликнем «Done»

И лишь после заполнения всей необходимой информации на этом шаге, кликнем «NEXT», что бы перейти к следующему.

ШАГ 2

Мы переходим на экран настройки команд обмена информацией между Adalo и внешней базой (в нашем случае с Quinta DB). Как написано в документации Adalo, в большинстве случаев здесь ничего менять не надо, но некоторые сервисы требуют уточнений.

Нам нужно внести уточнение только в тип команды, который отвечает за получение данных в Adalo из внешней базы, в раздел «Get All» — собственно в метод получения данных.

И там надо лишь указать в поле «Results key» — значение «records» — именно такое значение указывается как в случае со связью QuntaDB, так и в случае, если бы мы связывали БД Airtable.

Лишь после этого можем переходить к следующему экрану — NEXT.

ШАГ 3

На финальном экране формы связи Adalo предлагает протестировать корректность введёнными нами данных. Если всё ок — он позволит сохранить запись связи. Если нет — сообщит об ошибке и укажет её тип.

Жмём «RUN Test»

В нашем случае, всё отлично. Жмём «create collection».

Как мы видим на тестовом экране, к нам прилетели именно те данные, которые нам необходимы.

Теперь у нас есть постоянная связь с БД на QuintaDB и Adalo её воспринимает как собственную, а не как в случае с Zapier у нас лишь передавались бы данные тогда, когда Zapier инициировал бы срабатывание триггера. Ну, почти как собственную, есть нюансы, но они не для этой статьи.

И вот, задача решена. Ну, вроде как - есть нюанс.

Есть ещё один параметр, который нам надо будет добавить в настройку этой связи. Этот параметр команда поддержки QuintaDB разработала специально при разборе этого кейса. Вы сможете работать с БД QuintaDB в Adalo и без него, конечно. Но с ним всё будет проще значительно) Но, что бы выявить в нём потребность, я прежде покажу, как выглядит наша БД QuintaDB в Adalo без этого параметра.

Я подвязал в Adalo к нашей БД QuintaDB экран в приложении со списком мероприятий и теперь мне надо указать какие данные из БД куда подставлять:

Как только я начинаю выбирать колонки для подстановки, то видно, что в БД отображается не название колонок, как я их назвал в нашей таблице «Таблица мероприятий» в QuintaDB, а отображаются их ID (это уникальный идентификатор колонок в самой QiuntaDB).

Это, конечно, дико не удобно. Если для 4х свои колонок я ещё соотнесу их с такими названиями, то в случае, если колонок будет больше, все мы просто вскроемся.

И вот в пятницу команде из QuintaDB об этом написал и уже в понедельник они решили эту засаду:

В нашу строчке запроса надо добавить значение? name_value=1», т.е. строка запроса (она же API Base URL в форме) должна выглядеть теперь так:

Возвращаюсь к настройкам нашей связи с нашей внешней БД в Adalo и корректирую API Base URL, дописав в конце — ?name_value=1

Снова прохожу по остальным экранам формы и RUN TEST. Всё ок. Смотрю, что изменилось.

Отлично! Строк теперь стало больше (видны как названия колонок по ID, так и по имени). То, что остались названия по ID, на самом деле не мусор — для вычислений в Adalo эта информация может пригодится, предполагаю.

Вот теперь точно всё!)

Ещё месяц назад я ничего не знал практически за все эти инструменты, за исключением QuintaDB и Figma (на этих сервисах я уже ранее сделал несколько проектов), ну и лишь был наслышан несколько про Zapier.

Месяц назад прошёл пятидневный интенсив от компании "Product Sense" по взаимодействию Продакт менеджера с разработчиками. Интенсив отличный, за что спасибо всей команде. Но именно на 5-ом дне интенсива был финальный блок от Вадима Михайлова, основателя сообщества "Зерокодер", по созданию прототипа приложения (MVP) без кодирования. И вот после этого блока для меня началась новая жизнь — Спасибо Вад)

Присоединяйтесь к сообществу и жизнь ваша, стартаперская и менеджерская, станет проще и интереснее — там много про что и о чём) Сами видите, порог входа в новые инструменты гуманитарием — 2-3 дня. А что бы запустить свой MVP — две-три недели. Да ещё и экономика будет минимальной.

UPD от 2021-02-09 - Служба поддержки QuintaDB написала, что теперь их zap в Zapier отрабатывает все записи - и созданные, и импортированные, и клонированные. Супер - молодцы)