SOAP API

SOAP API (Simple Object Access Protocol) предоставляют стандартизированный способ обмена данными между системами, обычно с использованием XML в качестве формата сообщений и работы поверх протоколов, таких как HTTP, SMTP и других.

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

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

Различия между SOAP API и REST API:

Протокол и формат сообщений: SOAP основан на протоколе с использованием XML-сообщений, в то время как REST более гибкий, использует методы HTTP и поддерживает несколько форматов данных, таких как JSON и XML.

Жизненный цикл соединения: SOAP работает с независимыми запросами и ответами, в то время как REST безсостояние, где каждый запрос независим, что делает REST более масштабируемым и простым в управлении.

Сценарии использования: SOAP предпочтителен в случаях, где требуются формальные контракты и высокий уровень безопасности, в то время как REST лучше подходит для легковесных, масштабируемых веб-сервисов.

SOAP Example response
REST Example response

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <GetMatchScoreResponse xmlns="http://example.com/scores">
      <MatchScore>
        <Team1>Red Dragons</Team1>
        <Team2>Silver Sharks</Team2>
        <Score>2-1</Score>
      </MatchScore>
    </GetMatchScoreResponse>
  </soap:Body>
</soap:Envelope>

{
  "event": "match_score",
  "data": {
    "team1": "Red Dragons",
    "team2": "Silver Sharks",
    "score": "2-1"
  }
}

Создание приложения

Это руководство содержит пошаговые инструкции по добавлению и использованию SOAP API для создания примера приложения, которое отображает список стран. При нажатии на название страны пользователь переходит на страницу деталей, где отображается флаг страны. Следуя этим инструкциям, вы узнаете, как добавить SOAP API в приложение и создать базовый поток навигации.

Итоговое приложение выглядит так:

Что вы узнаете

Как создавать SOAP API.
Создание API с динамическими данными в теле запроса.
Разбор XML-ответа.
Как выполнять навигацию и передавать данные на новую страницу.

Для создания такого приложения вам понадобятся следующие страницы.

HomePage: Отображает список всех стран.
CountryDetails: Отображает флаг страны.

Вот как будет происходить навигация между этими страницами:

Navigation flow

Шаги по созданию приложения следующие:

1. Создание интерфейса

Начнем с создания интерфейса для обеих страниц.

1.1 Главная страница

На этой странице отображается список всех стран с использованием виджетов ListView и ListTile.

HomePage

1.2 Страница деталей страны

Эта страница отображает флаг страны с использованием виджета Image.

CountryDetails Page

2. Создание API

Для этого примера мы используем два API из коллекции Postman Public SOAP APIs. Вот они:

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

2.1 getCountries

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

к сведению

Важно отметить, что в запросах необходимо включать правильный заголовок, такой как "Content-Type: text/xml; charset=utf-8", и установить тип тела запроса в "Text".

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

2.2 getCountryFlag

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

Request body
Header

request-body

3. Создание пользовательских действий

API, добавленные на предыдущем шаге, возвращают результат в формате XML, который необходимо разобрать, чтобы извлечь релевантные данные или информацию. Это можно сделать с помощью пользовательского действия. Пользовательское действие может использовать пакет 'xml' для разбора XML-ответа и получения данных в формате, который легко отобразить в виджетах интерфейса.

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

3.1 parseListofCountries

Это пользовательское действие разбирает результат API getCountries и возвращает список стран в переменной List с типом String.

Вот код с объяснениями в комментариях:

// Automatic FlutterFlow imports
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

import 'package:xml/xml.dart';

Future<List<String>> parseListofCountries(String xmlResponse) async {
  final document = XmlDocument.parse(xmlResponse);
  final countryList = <String>[]; // Create an empty list to hold the countries

  // Find all elements with tag 'm:tCountryCodeAndName'
  final countryElements = document.findAllElements('m:tCountryCodeAndName');
  // Loop through all the 'm:tCountryCodeAndName' elements found above
  for (final countryElement in countryElements) {
    // Extract the country code from the element
    final countryCode = countryElement.findElements('m:sISOCode').single.text;
    // Extract the country name from the element
    final countryName = countryElement.findElements('m:sName').single.text;
    // Add the country code and name to the country list as a single string
    countryList.add('$countryCode - $countryName');
  }

  print(countryList);
  return countryList;
}

Вот как это выглядит после добавления:

Custom action to parse list of countries

3.2 parseCountryDetails

Это пользовательское действие разбирает результат API getCountryFlag. Оно использует цепочку методов для навигации к нужному элементу и получения URL флага.

Вот код с объяснениями в комментариях:

// Automatic FlutterFlow imports
import '/flutter_flow/flutter_flow_theme.dart';
import '/flutter_flow/flutter_flow_util.dart';
import '/custom_code/actions/index.dart'; // Imports other custom actions
import '/flutter_flow/custom_functions.dart'; // Imports custom functions
import 'package:flutter/material.dart';
// Begin custom action code
// DO NOT REMOVE OR MODIFY THE CODE ABOVE!

import 'package:xml/xml.dart';

Future<String> parseCountryDetails(String xmlResponse) async {
  final document = XmlDocument.parse(xmlResponse);

  return document
      .getElement('soap:Envelope')! // Access the soap:Envelope element
      .getElement('soap:Body')! // Access the soap:Body element
      .getElement('m:CountryFlagResponse')! // Access the m:CountryFlagResponse element
      .getElement('m:CountryFlagResult')! // Access the m:CountryFlagResult element
      .text // Retrieve the text value of the element
      .trim(); // Trim any leading or trailing whitespaces
}

Вот как это выглядит после добавления:

4. Отображение списка стран

Теперь вы можете перейти к отображению списка стран на HomePage. Вот шаги, которые нужно выполнить:

Откройте HomePage.
Создайте переменную состояния страницы (например, countries) для хранения списка стран. Она будет использоваться для привязки данных в ListView.
Выберите страницу и добавьте следующую цепочку действий.
1. Вызов API getCountries.
2. При успехе добавьте пользовательское действие для parseListOfCountries. Важно отметить, что вы должны передать результат предыдущего вызова API в качестве аргумента функции и установить API Response Options в Raw Body Text. Также добавьте Action Output Variable Name.
3. Добавьте действие обновления состояния страницы и установите значение переменной (например, countries) на основе вывода пользовательского действия (добавленного ранее). Убедитесь, что Update Type установлен в Rebuild Current Page.
В ListView генерируйте динамические дочерние элементы с использованием переменной состояния страницы.
Переменная состояния страницы хранит название страны и код как одну строку (например, Australia - AT). Чтобы отобразить название и код отдельно в ListTile, можно использовать встроенную функцию. Для отображения названия страны используйте var1.split("-")[1].trim(), где var1 — текущий элемент в списке. Для отображения кода страны используйте то же выражение, заменив [1] на [0].

5. Навигация на страницу деталей страны

При нажатии на название страны (ListView > виджет ListTile) вы перейдете на страницу CountryDetails и передадите код страны. Он будет использоваться для получения флага страны на следующем шаге.

Для этого:

Выберите виджет ListTile и добавьте действие навигации на страницу CountryDetails.
В этом действии нажмите кнопку Define. Это откроет страницу CountryDetails, где вы можете определить параметр, который примет код страны.
После определения параметра снова откройте это действие и передайте код страны с использованием кодового выражения, примененного на предыдущем шаге (например, var1.split("-")[0].trim()).

Parameter on CountryDetails page
Passing country code while navigating to CountryDetails page

Parameter on CountryDetails page

6. Отображение флага страны

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

Вот пошаговые инструкции:

Откройте CountryPage.
Создайте переменную состояния страницы с типом ImagePath (например, flagURL) для хранения URL изображения флага. Она будет использоваться для отображения в виджете Image.
Выберите страницу и добавьте следующую цепочку действий.
1. Вызов API getCountryFlag.
2. При успехе добавьте пользовательское действие для parseCountryDetails. Важно отметить, что вы должны передать результат предыдущего вызова API в качестве аргумента функции и установить API Response Options в Raw Body Text. Также добавьте Action Output Variable Name.
3. Добавьте действие обновления состояния страницы и установите значение переменной (например, flagURL) на основе вывода ранее добавленного пользовательского действия. Убедитесь, что Update Type установлен в Rebuild Current Page.
Теперь просто используйте переменную состояния страницы для отображения URL флага в виджете Image.

Получение примера приложения

Получите клонируемую версию этого приложения здесь.

SOAP API

Различия между SOAP API и REST API:​

Создание приложения​

1. Создание интерфейса​

1.1 Главная страница​

1.2 Страница деталей страны​

2. Создание API​

2.1 getCountries​

2.2 getCountryFlag​

3. Создание пользовательских действий​

3.1 parseListofCountries​

3.2 parseCountryDetails​

4. Отображение списка стран​

5. Навигация на страницу деталей страны​

6. Отображение флага страны​

Получение примера приложения​