Интеграция мобильных приложений с backend API¶
Требования применяются к сетевым вызовам iOS и Android. Уровни обязательности
определены в корневом README.md.
MOB-API-001. Версионируемый контракт¶
Уровень: MUST
Применяется к: каждому backend API
Проект должен фиксировать версию API-контракта. Модели и клиент должны генерироваться или автоматически проверяться по контракту. Клиент должен игнорировать неизвестные поля ответа, не меняющие известную семантику. Неизвестное значение enum должно иметь определённый fallback только для enum, заранее объявленного контрактом расширяемым; для закрытого enum добавление значения является несовместимым изменением.
Обоснование¶
Установленная версия приложения может жить дольше нескольких backend releases.
Проверка¶
- contract-тест старого клиента с новым полем и расширяемым значением enum;
- тест необъявленного значения закрытого enum;
- schema validation;
- compatibility gate в CI.
Исключения¶
API без схемы требует ADR и эквивалентного contract test.
MOB-API-002. Timeout, отмена и retry¶
Уровень: MUST
Применяется к: каждому сетевому вызову
Ограниченный вызов должен иметь конечный timeout и отменяться, когда результат
больше не нужен. Retry допускается только для временной ошибки и идемпотентной
операции либо операции с ключом идемпотентности; число попыток и время должны
быть конечными, с backoff и jitter. Retry-After должен учитываться.
Обоснование¶
Мобильная сеть часто меняется и не гарантирует быстрый явный отказ.
Проверка¶
- тест зависшего, отменённого и повторённого запроса;
- переключение сети во время операции;
- тест неидемпотентного результата.
Исключения¶
Намеренно долгоживущий поток MAY не иметь общего timeout, если контракт определяет конечные timeout установления и отсутствия прогресса, а также условие завершения.
MOB-API-003. Состояние сети и пользовательский результат¶
Уровень: MUST
Применяется к: неуспешному или отложенному вызову
Приложение должно различать отсутствие сети, timeout, аутентификацию, авторизацию, валидацию, конфликт, rate limit и технический отказ. Оно не должно считать системный индикатор сети доказательством доступности API. Пользователю должны сообщаться состояние операции и безопасное действие восстановления без внутреннего текста backend.
Обоснование¶
Наличие интерфейса сети не подтверждает маршрут до сервиса.
Проверка¶
- тест каждого класса ошибки;
- captive portal и потеря сети;
- review пользовательских сообщений.
Исключения¶
Не допускаются для различения неопределённого результата изменяющей операции.
MOB-API-004. Корреляция и фоновые запросы¶
Уровень: MUST
Применяется к: запросу внутри активной операции
Контекст трассы должен передаваться backend из закрытого allowlist по W3C Trace
Context: traceparent и tracestate, когда оно присутствует. Контекст не
должен передаваться endpoint вне allowlist. request_id и correlation_id
должны сохранять семантику из OBS-LOG-004 и не создаваться фиктивно. Фоновое
выполнение запроса должно соблюдать системный временной бюджет и сохранять
достаточно состояния для определения результата после возобновления.
Обоснование¶
Приложение может быть приостановлено до получения ответа.
Проверка¶
- сквозной trace test;
- тест отсутствия контекста для endpoint вне allowlist;
- тест suspension и relaunch;
- проверка отсутствия фиктивных ID.
Исключения¶
Протокол без metadata должен фиксировать ограничение в контракте.
MOB-API-005. Поддержка установленной версии¶
Уровень: MUST
Применяется к: ограничению backend-возможностей по версии установленного мобильного приложения
Версионируемый API-контракт должен различать доступное необязательное обновление, обязательное обновление неподдерживаемой версии, временное обслуживание и технический отказ. Обязательное обновление должно передаваться стабильным машинным кодом и указывать минимальную поддерживаемую публичную версию отдельно для затронутой платформы. Неизвестный ответ не должен интерпретироваться как требование удалить состояние или немедленно обновиться.
До включения обязательного обновления совместимый release должен быть доступен
каждому затронутому пользователю во всех объявленных для него production-
магазинах по MOB-BUILD-005. Ограниченный staged rollout не должен оставлять
пользователя одновременно без доступа к прежней версии и без возможности
получить требуемую.
Экран обновления не должен удалять credentials, локальные черновики или
неопределённые результаты операций только из-за версии приложения. Проект
должен определить, какие из них совместимы после обновления, а несовместимое
состояние должно получать явный безопасный результат по MOB-DATA-003.
Обоснование¶
Установленный клиент может оставаться активным после нескольких backend- release, а преждевременная блокировка способна оставить пользователя без доступного пути восстановления.
Проверка¶
- contract-тест необязательного и обязательного обновления, maintenance и технического отказа;
- тест доступности требуемой версии для каждого production-магазина;
- тест обязательного обновления во время staged rollout;
- upgrade-тест credentials, черновика и неопределённой операции.
Исключения¶
При security-инциденте опасная версия MAY блокироваться до доступности обновления по процедуре инцидента, если приложение показывает отдельный безопасный результат и не уничтожает локальные данные как следствие неподдерживаемой версии.