На этой странице вы узнаете основные концепции добавления API-вызова в ваш проект. Эти концепции являются строительными блоками для добавления API-вызова. В зависимости от определения API, вы можете использовать некоторые или все из этих концепций для успешной реализации вызова API в вашем проекте.

Вот они:

Заголовки

Заголовки обычно содержат метаданные, связанные с HTTP-запросом или ответом на вызов API. HTTP-заголовки в основном делятся на две категории:

  • Заголовки запроса содержат дополнительную информацию о ресурсе, который нужно получить, или о клиенте, запрашивающем ресурс.
  • Заголовки ответа содержат дополнительную информацию о ответе, который возвращает сервер.

Передача заголовков запроса

Некоторые из общих заголовков запроса, которые могут вам понадобиться при отправке запроса:

  • Authorization: Используется для аутентификации запроса.
  • Content-Type: Используется при отправке запроса POST/PUT/PATCH с телом сообщения.

Для передачи заголовка запроса:

  1. Выберите вкладку Headers и нажмите кнопку + Add Header.
  2. В поле ввода введите имя заголовка, затем двоеточие (:) и его значение (например, Content-Length: application/json).

Передача токена авторизации (как заголовка запроса)

Возможно, вам нужно добавить API, который защищен. Это означает, что он выдает результаты только при передаче токена авторизации (или auth токена) в параметре заголовка. Обычно это делается для предотвращения злоупотреблений. Давайте посмотрим, как можно добавить токен авторизации.

Передача статического токена авторизации

Некоторые сервисы предоставляют вам статический токен авторизации. Такой токен никогда не меняется, пока вы не сгенерируете новый вручную.

Для передачи статического токена авторизации:

  1. Выберите вкладку Headers и нажмите кнопку + Add Header.
  2. В поле ввода введите имя заголовка как Authorization, затем двоеточие (:) и его значение (например, Authorization: Bearer YOUR_TOKEN).

Передача динамического токена авторизации

Возможно, вам потребуется передать токен авторизации, возвращаемый в ответе вызова API для входа в систему. Такой токен меняется каждый раз при входе в систему. Поэтому вам нужен способ передать динамический токен.

После успешного выполнения вызова на вход, убедитесь, что вы сохранили токен аутентификации в переменной состояния приложения (с Persisted -> True). Посмотрите на изображения ниже:

Теперь вы можете передать динамический токен:

  1. Выберите вкладку Headers и нажмите кнопку + Add Header.
  2. В поле ввода введите имя заголовка как Authorization, затем двоеточие (:) и затем укажите любое имя переменной в квадратных скобках (например, Authorization: Bearer [auth_token]).
  3. Выберите вкладку Variables и создайте новую переменную с таким же именем, которое вы указали в квадратных скобках. Эта переменная будет использоваться для передачи значения токена из переменной состояния приложения в вызов API.

Теперь при вызове API (который требует токен аутентификации) передайте значение токена из переменной состояния приложения.

Доступ к заголовкам ответа

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

Для доступа к заголовку ответа:

  1. Убедитесь, что вы добавили API call action и указали Action Output Variable Name.
  2. Теперь, когда Value Source установлено как From Variable, выберите Action Outputs > [Action Output Variable Name] (например, Action Outputs > loginResponse).
  3. Установите API Response Options на Get Response Header.
  4. Введите Header Name. Обратите внимание, что это имя должно совпадать с именем заголовка ответа вашего вызова API.
  5. Нажмите Confirm.

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

Это необязательные параметры, которые вы можете передавать вместе с вызовом API; они помогают форматировать данные, возвращаемые сервером. Обычно они добавляются в конец URL с вопросительным знаком (?) в качестве разделителя и представлены в виде пар «ключ-значение».

Пример URL с параметрами запроса выглядит следующим образом (NASA Open API):

https://api.nasa.gov/neo/rest/v1/feed?start_date=2015-09-07&end_date=2015-09-08&api_key=DEMO_KEY

Здесь start_date, end_date и api_key — это параметры запроса, передаваемые для получения конкретных данных.

Вот еще один пример. В этом вызове API https://www.breakingbadapi.com/api/characters?limit=20&offset=0 используются два параметра запроса. Параметр limit указывает 20 элементов для загрузки на странице, а offset указывает количество пропускаемых элементов. Это называется пагинацией на основе смещения.

Передача параметров запроса

Чтобы передать параметры запроса для вызова API с методами GET или DELETE:

  1. Выберите вкладку Query Parameters и нажмите кнопку + Add Query Parameter.
  2. Введите Имя параметра запроса.
  3. Установите Источник значения на Specific Value или From Variable.
    1. Если вы хотите передать это значение из страницы, переменной состояния приложения или другого источника (т.е. динамическое значение), выберите From Variable, а затем из выпадающего списка Select Variable выберите уже созданную переменную (см. как создать переменную) или нажмите + Create New Variable. Примечание: Переменная будет немедленно создана с таким же именем, как параметр запроса. Однако вам все еще нужно открыть вкладку Variables и установить его Тип.
    2. Если вы хотите передать статическое/фиксированное значение, выберите Specific Value, установите его Тип и введите его Значение.

Пример передачи параметра запроса для URL -> https://api.instantwebtools.net/v2/passenger?page=10&size=20

В редких случаях вам может понадобиться передать параметры запроса для других методов вызовов API, таких как POST, PUT и PATCH. Для этого:

  1. В URL вашего API замените жестко заданные значения на осмысленные имена в скобках (например, из https://api.instantwebtools.net/v2/passenger?page=0 на https://api.instantwebtools.net/v2/passenger?page=[page]).
  2. Выберите вкладку Variables и создайте новую переменную с таким же именем, как указано в скобках.

Переменные

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

  • Передача токена авторизации из состояния вашего приложения в заголовок запроса API.
  • Использование имени пользователя и пароля из виджетов TextField в теле запроса API.
  • Включение выбранных дат в качестве параметров запроса.
  • Изменение базового URL на динамический URL.

Создание переменных

Чтобы создать переменные, выберите вкладку Variables, введите его Имя, выберите соответствующий Тип и при необходимости укажите Значение по умолчанию.

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

Пример использования переменной для создания динамического базового URL:

Тело запроса

Вы можете отправлять данные (в качестве тела запроса) при вызове API с методами POST, PUT или PATCH, определяя их внутри Body. Наиболее распространенный тип — это формат JSON, который является самым простым способом передачи данных в теле запроса.

Создание тела запроса

Здесь мы рассмотрим создание тела запроса в следующих форматах:

Формат JSON

Чтобы создать тело запроса в формате JSON:

  1. Если вы еще не сделали этого, создайте переменные (например, переменные имени пользователя и пароля, которые будут нужны для передачи значений со страницы входа в вызов API входа).
  2. Выберите вкладку Body и установите выпадающее меню Body на JSON.
  3. Скопируйте и вставьте ваше тело запроса и замените значения переменными, перетащив их в ваше тело JSON.

Формат текста

Этот формат используется для отправки текстовых данных в теле запроса API. Например, в SOAP API тело запроса обычно представлено в текстовом формате и содержит данные XML.

Чтобы создать тело запроса в текстовом формате:

  1. Если вы еще не сделали этого, создайте переменные.
  2. Выберите вкладку Body и установите выпадающее меню Body на Text.
  3. Скопируйте и вставьте ваше тело запроса и замените значения переменными, перетащив их в тело запроса.

x-www-urlencoded формат

Чтобы создать тело запроса в формате x-www-form-urlencoded:

  1. Если вы еще не сделали этого, создайте переменные (например, переменные имени пользователя и пароля, которые будут нужны для передачи значений со страницы входа в вызов API входа).
  2. Выберите вкладку Body и установите выпадающее меню Body на x-www-form-urlencoded.
  3. Нажмите на кнопку + Add Parameter и введите Имя параметра.
  4. Установите Источник значения на Specific Value или From Variable.
    1. Если вы хотите передать это значение со страницы, переменной состояния приложения или другого источника (т.е. динамическое значение), выберите From Variable, а затем из выпадающего списка Select Variable выберите уже созданную переменную (см. как создать переменную) или нажмите + Create New Variable. Примечание: Переменная будет немедленно создана с таким же именем, как параметр. Однако вам все еще нужно открыть вкладку Variables и установить его Тип.
    2. Если вы хотите передать статическое/фиксированное значение, выберите Specific Value, установите его Тип и введите его Значение.

Формат Multipart

Тело запроса в формате multipart — это формат данных, используемый в HTTP-запросах, который позволяет передавать несколько частей данных в одном запросе. Он часто используется для загрузки файлов.

Чтобы создать тело запроса в формате multipart:

  1. Выберите вкладку Body и установите выпадающее меню Body на Multipart.
  2. Нажмите на кнопку + Add Parameter и введите Имя параметра.
  3. Установите Источник значения на From Variable, затем из выпадающего списка Select Variable нажмите на + Create New Variable. Примечание: Переменная будет немедленно создана с таким же именем, как параметр.
  4. Теперь перейдите на вкладку Variables и установите Тип на Uploaded File. Это позволит вам передать файл, хранящийся локально на устройстве, используя действие, такое как Upload/Save Media.

Ответ API (JSON) к/от типа данных

Преобразование между ответом API (JSON) и типами данных часто называется десериализацией и сериализацией JSON. Оно позволяет вам преобразовать данные JSON из ответа API в Пользовательский тип данных при его получении. Также это позволяет вам преобразовать ваш пользовательский тип данных обратно в JSON при отправке данных в запросе API.

Это более надежный и поддерживаемый способ работы с данными JSON в вашем приложении. Он снижает сложность и вероятность ошибок (например, опечаток) по сравнению с ручной навигацией по JSON-путям.

Создание пользовательского типа данных, соответствующего структуре JSON

Сначала создайте тип данных с той же структурой, что и ваш ответ API. Вот пример, как JSON-ответ выглядит после преобразования в пользовательский тип данных.

Создание пользовательского типа данных в соответствии с JSON-ответом

После этого вы можете конвертировать в или из пользовательского типа данных в зависимости от ваших требований.

JSON в тип данных

Давайте рассмотрим, как получить JSON в пользовательский тип данных с использованием примера, в котором извлекается список продуктов с этого API. Вот как это выглядит:

Вот как это сделать:

  1. Сначала убедитесь, что вы создали пользовательский тип данных, который соответствует вашей структуре JSON.
  2. Откройте определение вызова API > вкладка Response & Test > Response Type > включите Parse as Data Type. Выберите Тип данных, в который вы хотите конвертировать. В этом примере это ‘AllProducts’.

  1. На ListView, после добавления запроса API на бекенд, получите доступ к значениям, установив следующие параметры.
    1. Generate Children from Variable путем установки API Response Options на As Data Type.
    2. Установите Available Options на Data Structure Field, так как мы хотим выбрать только конкретное поле, которое содержит список продуктов, а не другие элементы, такие как ‘total’ и ‘skip’.
    3. Select Field для поля, которое содержит список продуктов, например, ‘products’ в этом примере.
    4. Нажмите Confirm дважды.
  1. Теперь вы можете привязать данные к элементам пользовательского интерфейса так же, как вы обычно делаете, установив Available Options на Data Structure Field и выбрав Select Field, которое хотите отобразить.

JSON из типа данных

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

Давайте рассмотрим пример добавления продукта, отправляя его данные в формате JSON в запросе API.

Вот как это сделать:

  1. Сначала создайте пользовательский тип данных, который соответствует формату JSON тела запроса API. Вот как это выглядит в этом примере.

  1. В вашем вызове API создайте переменную типа JSON и поместите ее в раздел Body.
  1. При нажатии на кнопку Add мы сохраняем значения из пользовательского интерфейса в переменной состояния страницы пользовательского типа данных. Затем, выполняя вызов API, передайте эту переменную состояния страницы и установите Available Options на To JSON.

JSON Path

JSONPath — это язык запросов для JSON. Используя JSONPath, вы можете извлекать определенные данные из всего JSON-ответа.

Обычно вы получаете ответ в формате JSON при выполнении запроса API.

Изучение некоторых путей JSON (или выражений JSONPath) поможет вам извлекать большинство данных, которые вам нужны. В нашем конструкторе мы позволяем вам пробовать и добавлять различные пути JSON в реальном времени, а также предлагать различные варианты для получения точных данных, которые вам нужны.

Примеры выражений JSONPath:

  • $.data.name
  • $.users[0].name
  • $.users[:].name

Лидирующий символ $ представляет корневой объект, точка (.) используется для доступа к ключам, находящимся внутри JSON, значение в квадратных скобках ([0]) представляет индекс массива, если ключ содержит массив, а ([:]) выбирает все объекты в списке.

Рассмотрим реальные примеры путей JSON для следующего ответа API:

{
  "page": 1,
  "per_page": 6,
  "total": 3,
  "total_pages": 2,
  "data": [
    {
      "id": 1,
      "email": "george.bluth@reqres.in",
      "first_name": "George",
      "last_name": "Bluth",
      "avatar": "https://reqres.in/img/faces/1-image.jpg"
    },
    {
      "id": 2,
      "email": "janet.weaver@reqres.in",
      "first_name": "Janet",
      "last_name": "Weaver",
      "avatar": "https://reqres.in/img/faces/2-image.jpg"
    },
    {
      "id": 3,
      "email": "emma.wong@reqres.in",
      "first_name": "Emma",
      "last_name": "Wong",
      "avatar": "https://reqres.in/img/faces/3-image.jpg"
    }
  ],
  "support": {
    "url": "https://reqres.in/#support-heading",
    "text": "To keep ReqRes free, contributions towards server costs are appreciated!"
  }
}
$.total

Это вернет следующие данные:

3
$.data

Это вернет следующие данные:

[
   {
      "id": 1,
      "email": "george.bluth@reqres.in",
      "first_name": "George",
      "last_name": "Bluth",
      "avatar": "https://reqres.in/img/faces/1-image.jpg"
   },
   {
      "id": 2,
      "email": "janet.weaver@reqres.in",
      "first_name": "Janet",
      "last_name": "Weaver",
      "avatar": "https://reqres.in/img/faces/2-image.jpg"
   },
   {
      "id": 3,
      "email": "emma.wong@reqres.in",
      "first_name": "Emma",
      "last_name": "Wong",
      "avatar": "https://reqres.in/img/faces/3-image.jpg"
   }
]
$.data[0]

Это вернет объект по индексу 0 (т.е. первый объект).

{
   "id": 1,
   "email": "george.bluth@reqres.in",
   "first_name": "George",
   "last_name": "Bluth",
   "avatar": "https://reqres.in/img/faces/1-image.jpg"
}
$.data[0].email

Это вернет значение email объекта по индексу 0.

"george.bluth@reqres.in"
$.data[:].email

Это вернет email всех объектов в data.

[
  "george.bluth@reqres.in",
  "janet.weaver@reqres.in",
  "emma.wong@reqres.in"
]

:::warning[Важно]
Ключи JSON должны начинаться с буквы, подчеркивания или знака доллара. Они не могут начинаться с числового символа. Однако в случаях, когда ключи имеют числовые префиксы, например $.0_image, вы можете получить к ним доступ с помощью нотации скобок, вот так: $.["0_image"].
:::

Подробнее узнайте о JSONPath и как правильно определять выражения.

Добавление JSON Path

Чтобы добавить JSON Path:

  1. Сначала создайте и протестируйте ваш вызов API.
  2. Во вкладке JSON Paths нажмите кнопку + Add JSON Path.
  3. Введите ваш JSON Path и дайте ему Имя.
  4. Если вы ввели корректное выражение, начальная часть ответа будет отображена в колонке Response Preview. Чтобы увидеть полный ответ, нажмите на значок Preview.
  5. Если возвращенный ответ является списком элементов, по умолчанию Is List будет отмечен; однако, если вы хотите явно преобразовать ответ в список, отметьте галочкой.
  6. Также мы рекомендуем все возможные JSON-пути (во вкладке Recommended), которые могут включать то, что вам нужно.
    1. Чтобы добавить рекомендованный JSON-путь, отметьте Selected, откройте вкладку Selected и дайте ему имя.

Использование JSON Path

При доступе к значениям из вызова API вы можете либо ввести пользовательский JSON Path, либо использовать уже созданный JSON Path.

Чтобы использовать уже добавленный JSON Path:

  1. Выберите ваш ответ API.
  2. Установите API Response Options на JSON Body.
  3. Установите Available Options на JSON Path.
  4. Установите JSON Path Name на то имя, которое вы создали ранее.

Дополнительные настройки

Вы можете сделать вызов API приватным и изменить настройки прокси с помощью дополнительных настроек.

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

Создание приватного вызова API полезно, если он использует токены или секреты, которые вы не хотите раскрывать в вашем приложении. Включение этой настройки будет маршрутизировать вызов API безопасно через Firebase Cloud Functions.

Чтобы сделать вызов API приватным, откройте вкладку Advanced Settings, включите переключатель Make Private, нажмите Save, затем Deploy APIs.

При необходимости вы можете принудить пользователя пройти аутентификацию через Firebase для выполнения этого вызова API. Для этого включите переключатель Require Authentication.

Информация:

  • Если вы делаете вызов API приватным, Firebase должен быть подключен к вашему проекту. Следуйте инструкциям на этой странице для интеграции Firebase с FlutterFlow.
  • Если вы включаете переключатель Require Authentication, Firebase Authentication должен быть настроен соответствующим образом. Подробнее о настройке аутентификации вы можете узнать на этой странице.

Обработка потокового ответа

При работе с API, которые отправляют данные непрерывно, например, с серверными событиями (SSE), вы можете включить эту опцию. Это гарантирует, что ваше приложение сможет обрабатывать постоянный поток данных по долговременному HTTP-соединению для отображения обновлений в реальном времени.

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

Информация:
Обычно вы можете определить, поддерживает ли API потоковую передачу, проверив его документацию. Ищите такие ключевые слова, как «event stream» или «processing chunks».

Примечание:
Узнайте больше о добавлении и использовании Streaming APIs.

Изменение настроек прокси

По умолчанию, когда вы тестируете свои вызовы API в нашем конструкторе, режиме Run и Test, мы используем прокси для маршрутизации вызовов, чтобы избежать проблемы CORS. Однако, если вы хотите использовать свой прокси, вы можете отключить эти настройки и указать свой URL прокси.

Чтобы отключить текущие настройки прокси и указать свой URL прокси:

  1. Откройте вкладку Advanced Settings.
  2. Отключите Use Proxy for Test и/или Use Proxy for Run/Test Mode.
  3. Включите Use Custom Proxy URL.
  4. Введите Proxy Prefix URL (например, https://your-proxy-server.com).

Кеширование результатов API

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

Декодирование ответов как UTF-8

Включение этой опции гарантирует, что данные, которые вы получаете от сервера или веб-сайта, будут читаться в формате UTF-8, что является распространенным способом хранения текста. Обычно сервер или сайт сообщает вам, как читать его данные, но иногда этого не происходит. Эта опция гарантирует, что вы читаете данные в формате UTF-8, даже если сайт не сообщает вам об этом.

API Интерсепторы

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

Интерсептор действует как посредник между вашим приложением и сервером API. Таким образом, когда вы делаете вызов API из своего приложения, запрос сначала проходит через интерсептор. Интерсептор может проверить запрос, изменить его (например, добавить заголовки или изменить URL) и даже отменить запрос при необходимости. Аналогично, когда сервер отвечает на ваш запрос, ответ проходит через интерсептор перед тем, как достичь вашего приложения.

Рассмотрим, как добавить интерсептор:

  1. Перейдите на вкладку Advanced Settings.
  2. Нажмите на + Add Interceptors и выберите + Create New Interceptor, чтобы открыть редактор Custom Action.
  3. Введите Имя действия (Action Name).
  4. В шаблоне кода добавьте ваш пользовательский код внутри функции onRequest для перехвата и изменения запросов, а также внутри функции onResponse для перехвата и изменения ответов.

Совет:
Вы можете скопировать шаблон кода в ChatGPT и попросить завершить код для конкретного интерсептора. Вот пример. Однако финальные корректировки могут потребоваться.

  1. Сохраните действие (Save Action) и проверьте наличие ошибок.
  2. Новосозданный интерсептор будет добавлен в список API интерсепторов.

Совет:

  • Вы можете добавить несколько интерсепторов к любому вызову API.
  • Когда один и тот же интерсептор используется несколькими API, вы можете создать группу API и добавить интерсептор в Advanced Group Settings. Однако вы можете переопределить интерсептор для любого API внутри группы, если это необходимо.

Совет: Если вам удобнее смотреть видеоурок, вот один для вас: