Вызовы API 101

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

Вот они:

• Заголовки
• Параметры запроса
• Переменные
• Тело
• Путь JSON
• Тип данных JSON в/из

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

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

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

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

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

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

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

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

Чтобы передать статический токен:

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

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

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

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

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

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

Чтобы получить доступ к заголовку ответа:

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

Это необязательные параметры, которые можно передать при вызове 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

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

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

Чтобы передать параметры запроса для вызова API GET или DELETE, выберите вкладку Параметры запроса и нажмите кнопку + Добавить параметр запроса:

1. Выберите вкладку Параметры запроса и нажмите кнопку + Добавить параметр запроса.
2. Введите имя параметра запроса.
3. Установите для параметра Value Source значение Specific Value или From Variable.
   1. Если вы хотите передать значение из страницы, переменной состояния приложения или любого другого источника (т. е. динамическое значение), выберите From Variable, а затем из выпадающего списка Select Variable выберите уже созданную переменную (см. как создать переменную) или нажмите на + Create New Variable. Примечание: Это сразу же создаст новую переменную с тем же именем, что и параметр запроса. Однако вам все равно придется открыть вкладку Переменные и задать ее Тип.
   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. Выберите вкладку «Переменные» и создайте новую переменную с тем же именем, которое вы указали в скобках.

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

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

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

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

Вот как можно использовать переменную для создания динамического базового URL:

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

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

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

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

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

Чтобы создать тело запроса в текстовом формате, выполните следующие действия:

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

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

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

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

Чтобы создать тело запроса в формате multipart, выполните следующие действия:

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

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

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

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

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

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

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

В ListView, после добавления запроса API-вызова бэкенда, получите доступ к значениям, установив следующие параметры.

1. Сгенерируйте Children из переменной, установив для параметра API Response Options значение As Data Type.
2. Установите Available Options в Data Structure Field, потому что мы хотим захватить только конкретное поле, содержащее список товаров, а не другие элементы, такие как ‘total’ и ‘skip’.
3. Выберите Field для поля, содержащего список товаров, т. е. ‘products’ для данного примера.
4. Дважды нажмите кнопку Подтвердить.

• Теперь вы можете связать данные в элементах пользовательского интерфейса, как это обычно делается, установив в параметрах Available Options (Доступные параметры) значение Data Structure Field (Поле структуры данных) и Select Field (Выбор поля), которое вы хотите отобразить.

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

Рассмотрим пример добавления товара с передачей его данных в формате JSON в запросе API.

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

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

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

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

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

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

Некоторые примеры выражений JSONPath выглядят следующим образом:

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

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

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

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

1. Сначала создайте и протестируйте вызов API.
2. В разделе Пути JSON нажмите на кнопку + Добавить  JSON Path.
3. Введите свой JSON-Path и дайте ему имя.
4. Если вы ввели правильное выражение, вы увидите начальную часть ответа в колонке «Просмотр ответа». Чтобы увидеть полный ответ, нажмите на значок «Предварительный просмотр».
5. Если возвращаемый ответ представляет собой список элементов, по умолчанию будет установлен флажок Is List; однако если вы хотите явно преобразовать ответ в список, отметьте его.
6. Мы также рекомендуем все возможные пути JSON (на вкладке «Рекомендуемые»), которые могут включать то, что вы ищете.
   1. Чтобы добавить рекомендуемый путь JSON, отметьте его, откройте вкладку Selected и дайте ему имя.

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

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

1. Выберите ответ API.
2. Установите для параметра Параметры ответа API значение Тело JSON.
3. Установите для параметра Доступные параметры значение Path JSON.
4. Установите имя Path JSON на то, которое вы создали ранее.

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

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

Чтобы сделать вызов API приватным, откройте вкладку «Дополнительные настройки», включите тумблер «Сделать приватным», нажмите «Сохранить», а затем «Развернуть API».

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

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

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

1. Откройте вкладку «Дополнительные настройки».
2. Отключите опцию Use Proxy for Test и/или Use Proxy for Run/Test Mode.
3. Включите параметр Использовать пользовательский URL прокси.
4. Введите URL-адрес префикса прокси (например, https://your-proxy-server.com).

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

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