Экспертный материал 4Sides
API для обмена данными в корпоративной логистике
Хороший логистический API описывает не только успешный запрос. Он сохраняет совместимость при развитии сервиса, не создаёт дубли при повторной отправке и позволяет восстановить историю каждой операции.
Как спроектировать устойчивый контракт API для заявок, статусов и справочных данных: версии, защита от дублей и журнал операций.
Версионирование
Версия API фиксирует набор полей, правила проверки и смысл статусов. Изменения, нарушающие совместимость, выпускаются отдельно, а клиент получает понятный период для перехода.
Проверьте перед запуском
- разделять совместимые и несовместимые изменения
- публиковать описание версии и дату прекращения поддержки
- тестировать старых клиентов до выпуска обновления
Защита от повторного создания заявки
Повторный запрос с тем же уникальным ключом должен возвращать исходный результат, а не создавать вторую заявку. Это особенно важно при сетевых сбоях, когда система клиента не знает, был ли принят первый запрос.
Проверьте перед запуском
- передавать уникальный ключ операции
- хранить результат обработки в согласованный период
- явно сообщать о конфликте данных при повторе
История операций
История связывает запрос, ответ, пользователя, время и действие в системе. Она нужна для разбора ошибок и контроля обмена, но не должна бесконтрольно копировать персональные данные и секреты.
Проверьте перед запуском
- использовать единый номер запроса
- маскировать токены (электронные ключи доступа) и чувствительные поля
- зафиксировать срок хранения и права доступа