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