Создание и проверка вызова API

Через вызовы API приложение общается с внешними сервисами: получает свежие данные и пользуется чужой функциональностью. Разберём, как создать такой вызов и проверить его прямо в конструкторе.

Создание вызова

Откройте API Calls в левом меню, нажмите + Add и выберите Create API Call. Задайте API Call Name, выберите Method Type (GET, POST, DELETE, PUT или PATCH) и укажите адрес сервиса.

Динамические адреса

Часть адреса может меняться: https://reqres.in/api/users/2, где 2 — идентификатор пользователя, или https://reqres.in/api/users?page=5, где 5 — номер страницы.

1. Замените жёстко заданное значение осмысленным именем в квадратных скобках: https://reqres.in/api/users/[user_id].
2. Создайте переменную с тем же именем.

Дальнейшие шаги зависят от выбранного метода.

Запросы GET и DELETE

1. Если запросу нужны заголовки — скажем, токен авторизации, — добавьте их.
2. Если нужны параметры запроса — номер страницы, идентификатор, — добавьте их.
3. Нажмите Add Call.

В примере выше запрос GET получает данные пользователей с REQ | RES — сервиса с тестовым REST API.

А вот тот же запрос с динамическим адресом:

Как его собрать:

1. Замените жёстко заданное значение именем в скобках: https://reqres.in/api/users/[user_id].
2. Создайте переменную с тем же именем.

Запрос DELETE описывается так же — отличается только выбранный Method Type.

Запросы POST, PUT и PATCH

1. Если запросу нужны заголовки, добавьте их.
2. Опишите тело запроса.
3. Нажмите Add Call.

В примере запрос POST использует две переменные — userName и userJob, — которые подставляются в тело запроса JSON.

Запросы PUT и PATCH описываются так же: важно указать правильный адрес и метод.

Группы вызовов

Вызовы с общим базовым адресом объединяют в группу. Заголовки — например, токен авторизации — задаются один раз на всю группу и подставляются в каждый вызов.

Как создать группу:

1. Нажмите + слева вверху и выберите Create API Group.
2. Задайте API Group Name.
3. Укажите API Base URL — общую часть адреса. Слэш в конце не нужен.
4. Кнопкой + Add Header добавьте заголовки — подробнее о них.
5. Нажмите Add Group — группа появится в списке слева.
6. Откройте её и нажмите + Add API Call.
7. Опишите вызов как обычно, указав в адресе только ту часть, что идёт после базового URL.

Импорт описаний API

Описания вызовов можно импортировать пачкой из Swagger/OpenAPI — вместо того чтобы заводить десятки запросов руками.

Заодно это избавляет от опечаток, которые при ручном вводе неизбежны.

Как импортировать:

1. Нажмите значок Import OpenAPI — откроется окно Import API Definitions.
2. Перетащите файл Swagger/OpenAPI в область загрузки или нажмите Browse files и выберите его. Подходят .json, .yaml и .yml, по одному файлу за раз.
3. Если в проекте ещё нет ни вызовов API, ни групп, а файл импортируется без предупреждений, FlutterFlow сразу добавит вызовы и закроет окно. В остальных случаях откроется окно Review API import: просмотрите изменения и нажмите Import APIs (при обновлении группы — Apply updates).
4. После импорта вызовы появятся в виде группы с именем из поля info.title файла. Если заголовка в файле нет, допишите его перед импортом.

Пример массового импорта — файл взят отсюда.

Проверка изменений перед импортом

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

Вверху окна задаются:

• Import into — Create a new API group либо Update с именем существующей группы. Группа подставляется сама, только если её имя совпадает с заголовком в файле.
• Import mode — появляется при обновлении группы:
  • Preserve configuration — применить выбранные изменения и сохранить переменные, разбор ответов и настройки;
  • Reset configuration — заменить группу содержимым файла и сбросить конфигурацию. Недоступно, если часть эндпоинтов из файла импортировать не удалось.

Change file — загрузить другой файл.

Слева перечислены Group & shared changes и все вызовы из файла. У каждого вызова пометка Added, Updated или Removed, сверху — счётчики. Changes only скрывает вызовы без изменений.

У выбранного элемента три вкладки:

• Configuration — изменения по полям: URL, переменные, заголовки и прочие настройки. Каждое изменение можно включить или пропустить. Если вы правили поле во FlutterFlow и файл тоже его меняет, такое изменение по умолчанию снято, чтобы не затереть вашу правку.
• Swagger source — Previous Swagger и Uploaded Swagger бок о бок, включая схемы, на которые ссылается вызов. Изменения схем ответа видны здесь для сверки, но разбор ответа по ним FlutterFlow не генерирует.
• After import — какой получится конфигурация с текущим выбором.

Если вызов уже используется в приложении, в деталях видно, сколько действий и запросов на него завязано.

Apply updates сохраняет выбранные изменения; если вы удаляете вызовы, FlutterFlow попросит подтвердить. В режиме Reset configuration кнопка называется Replace all, и подтвердить нужно потерю текущих значений переменных, разбора ответов и настроек.

Пропущенные изменения, которые не конфликтуют с вашими правками, при следующем импорте того же файла предложат снова.

Тестирование

Вызов стоит проверить до того, как он попадёт в приложение, — прямо в конструкторе.

1. Выберите вызов и откройте вкладку Response & Test.
2. Слева, в разделе Variables, задайте значения переменных.
3. Справа, в разделе Preview, видно адрес, заголовки, тело запроса и ответ. Вкладка Test Response показывает ответ целиком: JSON, сырой текст и заголовки.
4. Нажмите Test API Call. Появится статус запроса, а при успехе (код 200) — и полученные данные.
5. К любому значению из ответа можно обратиться, задав JSON-путь.

Ниже — проверка создания пользователя запросом POST с переменными userName и userJob. Успешный запрос возвращает код 201.

Действие API Call

Описанные вызовы доступны везде, где нужны.

Откройте редактор действий на нужном виджете, выберите триггер, найдите в списке действий «API Calls» и укажите нужный вызов.

Порядок действий:

1. Выделите виджет — например, кнопку.
2. В панели свойств выберите Actions и нажмите Open — откроется редактор действий.
3. Нажмите + Add Action.
4. Найдите действие API Call (раздел Backend/Database).
   1. Выберите Group or Call Name.
   2. Если вызову нужны переменные — токен, параметры, идентификатор, — задайте их кнопкой + Variable.
   3. Action Output Variable Name — имя переменной с ответом. По умолчанию оно случайное; лучше заменить его на осмысленное, например loginResponse.
   4. Добавьте условное действие, проверяющее успех вызова.
   5. В ветке TRUE опишите, что делать при успехе: например, перейти на главную после входа.
   6. В ветке FALSE — что делать при ошибке: например, показать сообщение.