Интеграция внешней CMS и корпоративного back-office через REST API часто выглядит просто на бумаге: аутентификация, эндпоинты CRUD, синхронизация. На практике встречаются три сценария: односторонняя синхронизация контента, двунаправленный обмен (включая статусы/метаданные) и потоковая загрузка медиа/бинарных данных. Каждый сценарий предъявляет свои требования к контракту, схемам и обработке ошибок.
Ниже — реальные проблемы, которые я видел в интеграциях с нестандартными back-office, и признаки их наличия:
Несогласованная модель данных. Поля в CMS и БД back-office имеют разные семантики: например, «author» в CMS — строка, а в back-office — объект с id и ролью. Симптом: успешный 200, но контент «ломается» при выводе.
Неправильная обработка идемпотентности. Повторные запросы создают дубликаты. Симптом: две записи после ре-отправки формы.
Ошибки при загрузке файлов. Back-office требует multipart/form-data с дополнительными метаданными, а CMS шлёт прямой PUT. Симптом: 415 Unsupported Media Type или пустые ссылки на файлы.
Тайм-ауты и несогласованность транзакций. При пакетной синхронизации часть операций проходит, часть откатывается локально. Симптом: частично применённые изменения и расхождение статусов.
Пагинация и сортировка. Back-office отдаёт cursor-based страницы, а CMS ожидает offset. Симптом: потерянные записи при синке.
Решения должны быть простыми и воспроизводимыми. Набор рекомендованных патчей:
Явные схемы трансформации. Используйте слой маппинга: для каждого ресурса описывайте правила преобразования типов и имен полей. Пример правила: если incoming.author — строка, создать объект {id: null, displayName: value}.
Идемпотентные ключи. Добавьте внешний идентификатор (external_id) и при POST сначала делайте GET по external_id; если найдено — PATCH. Это устраняет дубли при повторных вызовах.
Файлы через прокси. Для CMS‑интеграция делайте staged upload: CMS загружает файл в временное хранилище, получает URL, затем back-office принимает ссылку и подтверждает при завершении. Если требуется multipart, делайте отдельный шаг конвертации.
Пакетная обработка с контрольными суммами. Делите операции на атомарные чанки и помечайте каждый chunk контрольной суммой и статусом. При сбое повторяйте только последние неприменённые чанки.
Адаптеры пагинации. Напишите промежуточный слой, который переводит cursor ↔ offset и сохраняет маркеры последней страницы.
Простой curl-микро-пример идемпотентного создания записи:
curl -H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"external_id":"cms-123","title":"Заголовок"}' \
https://backoffice.example/api/items/upsert
Технические патчи стоит сопровождать практиками: логирование входящих payload, трассировка request-id через все системы, алерты на расхождения в количестве записей после синка. Регулярные контрактные тесты API помогут обнаружить регрессии при эволюции схем.
REST API при CMS‑интеграция с нестандартным back-office становится безопаснее и предсказуемее, если внедрить три уровня защиты: контрактный слой (схемы и трансформеры), идемпотентность и надежную обработку файлов/транзакций. Маленький адаптер между CMS и back-office часто дешевле и надежнее попыток поменять обе стороны. Внедрите контрольные проверки и пакетную стратегию — это уменьшит операционные разрывы и ускорит отладку.