JSON API для мобильных и внешних приложений
API как отдельная поверхность платформы
Выделенный HTTPS JSON API предоставляет мобильным, корпоративным и внешним приложениям структурированный доступ к явно опубликованным командам модулей. API не является обходным путём к базе данных и не превращает клиента в доверенный источник идентичности. Он использует те же бизнес-ограничения, проверки и операции, которые действуют в остальных поверхностях Sapphire I.C.D.S.
Что получает клиент
Клиент получает контракт команды: название операции, схему аргументов, допустимые значения и форму ответа. Сервер проверяет аутентификацию, текущего пользователя, область данных, права группы, состояние модуля и ограничения конкретной записи. Результат представляет только разрешённую проекцию и не обязан повторять внутреннюю таблицу или административную форму.
Так мобильное приложение может работать с каталогом, планом, контентом или рабочим процессом, не зная деталей Mirage, SQLMacros и внутреннего shell. Изменение веб-дизайна не должно ломать API, а обновление API должно проходить через совместимость и версионирование.
Почему API не равен прямому доступу к базе
Прямой доступ к базе смешивает транспорт, идентичность и структуру хранения. JSON API, напротив, связывает команду с авторизованной бизнес-операцией. Модуль проверяет владельца, связи, типы, длину, диапазоны и состояние объекта до изменения. Запрос не может сам выбрать произвольную таблицу, колонку или SQL-оператор.
Даже если внутри используется общая операция для веба, AI и API, внешний адаптер должен ограничивать опубликованный каталог. Переиспользуется проверенная логика, но не внутренний контекст и не все административные возможности.
Аутентификация и область данных
HTTPS защищает транспорт, но само по себе не даёт права на действие. Сервер связывает запрос с подтверждённым пользователем или техническим клиентом, применяет срок действия и правила отзыва токена, затем снова проверяет права на конкретную команду. Идентификатор пользователя, присланный в JSON, не может заменить серверно установленную личность.
Каждая команда должна ясно определить, какие данные ей доступны, какие поля можно читать, какие изменения разрешены и как фиксируется аудит. Ошибка одного вызова возвращается как результат этой операции и не должна расширять доступ к соседним командам.
Версии, ошибки и совместимость
API-контракт следует менять контролируемо. Несовместимое изменение схемы требует новой версии или отдельной команды, понятного периода перехода и проверки клиентов. Ошибки должны иметь стабильную машинную форму без утечки секретов и внутренних трассировок. Сообщение для оператора может быть подробным в журнале, но публичный ответ должен раскрывать только необходимое.
Практическая проверка интеграции
- Проверить TLS, срок действия и отзыв используемого способа аутентификации.
- Проверить доступ с минимальными правами и отдельно проверить отказ при недостаточной роли.
- Проверить валидацию типов, пустых значений, Unicode, длины и границ.
- Проверить повторный запрос, конкурентное изменение и идемпотентность там, где она нужна.
- Проверить, что ответ не содержит закрытые поля, внутренние инструкции или неэкранированный пользовательский HTML.
- Проверить журналирование команды без записи секретов и bearer-значений.
Когда JSON API приносит пользу
API особенно полезен, когда одна бизнес-логика должна обслуживать нативное приложение, корпоративный кабинет, интеграцию партнёра и автоматизированный процесс. Он создаёт стабильную машинную поверхность, не заставляя внешнего клиента имитировать HTML-форму. При этом публикация выполняется постепенно: сначала безопасные операции чтения, затем строго необходимые изменения с отдельным контролем.
Выделенный JSON API даёт приложениям доступ к возможностям Sapphire I.C.D.S. без зависимости от визуального интерфейса и без прямого доступа к БД. Его надёжность определяется не самим форматом JSON, а серверной аутентификацией, авторизацией, типизированным контрактом, аудитом и дисциплиной версионирования.