Перейти к основному содержимому

Вызовы API

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

Они включают:

Заголовки​

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

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

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

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

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

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

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

к сведению

По умолчанию Content-Type для любого HTTP POST запроса — application/json, поэтому, если ваше тело данных в формате JSON, вы можете не определять Content-Type.

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

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

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

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

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

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

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

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

Как сохранить токен авторизации?

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

api-token-variable.png

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

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

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

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

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

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

  1. Убедитесь, что вы добавили действие вызова API и указали 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 указывает количество элементов для загрузки на странице, а offset определяет количество пропущенных элементов. Это называется пагинацией с использованием смещения.

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

Для передачи параметров запроса для вызова API GET или DELETE:

  1. Выберите вкладку Query Parameters и нажмите + Add Query Parameter.
  2. Введите Name параметра запроса.
  3. Установите Value Source как Specific Value или From Variable.
    1. Если вы хотите передать это значение со страницы, переменной состояния приложения или другого источника (т.е. динамическое значение), выберите From Variable, а затем из выпадающего списка Select Variable выберите уже созданную переменную (см. как создать переменную) или нажмите + Create New Variable. Примечание: Это сразу создаст новую переменную с именем, совпадающим с именем параметра запроса. Однако вам всё равно потребуется открыть вкладку Variables и установить её Type.
    2. Если вы хотите передать статическое/фиксированное значение, выберите Specific Value, установите его Type и введите 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, введите Name переменной, выберите соответствующий Type и укажите Default Value, если необходимо.

variables.png

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

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

dynamic-base-url.png

Тело запроса​

Можно отправлять данные (в виде тела запроса) при вызове 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 и введите Name параметра.
  4. Установите Value Source на Specific Value или From Variable.
    1. Если вы хотите передать это значение с вашей страницы, переменной состояния приложения или другого источника (т.е. динамическое значение), выберите From Variable, а затем в выпадающем списке Select Variable выберите уже созданную переменную (см. как создать переменную) или нажмите + Create New Variable. Примечание: Это сразу создаст новую переменную с именем, совпадающим с именем параметра. Однако вам всё равно нужно будет открыть вкладку Variables и установить его Type.
    2. Если вы хотите передать статическое/фиксированное значение, выберите Specific Value, установите его Type и введите Value.

Формат Multipart​

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

Для создания тела запроса в формате Multipart:

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

Ответ API (JSON) в/из Типа данных​

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

к сведению

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

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

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

custom-data-type-json-response.png

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

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

JSON в Тип данных​

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

img.png

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

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

img_1.png

  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.

add-product.png

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

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

img_2.png

  1. В вашем вызове API создайте переменную с типом JSON и поместите её в Body.

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

JSON Path​

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

примечание

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

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

Некоторые примеры выражений JSONPath:

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

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

Давайте рассмотрим несколько примеров JSONPath для следующего ответа 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"
]

Важно

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

к сведению

Узнайте больше о JSONPath и о том, как правильно задать выражение.

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

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

  1. Сначала создайте и протестируйте ваш API-запрос.

  2. В разделе JSON Paths нажмите кнопку + Add JSON Path.

  3. Введите ваш JSON Path и задайте ему Name.

  4. Если вы ввели корректное выражение, вы увидите начальную часть ответа в колонке Response Preview. Чтобы увидеть полный ответ, нажмите на значок Preview.

  5. Если возвращаемый ответ является списком элементов, по умолчанию будет установлено значение Is List. Однако, если вы хотите явно преобразовать ответ в список, установите этот флажок.

  6. Мы также рекомендуем все возможные JSON-пути (вкладка Recommended), которые могут включать то, что вы ищете.

    1. Чтобы добавить рекомендованный JSON-путь, установите флажок Selected, откройте вкладку Selected и задайте ему имя.

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

При доступе к значениям из API-запроса вы можете ввести пользовательский 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.

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

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

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