Статус 

Поддержка ключей идемпотентности частична в настоящий момент. Избранные внутренние мутации повторных попыток — например, потоки повторных попыток выставления счетов заказов и повторные попытки возврата средств — уже принимают ключ идемпотентности и используют его для дедупликации нижестоящих вызовов процессора платежей. На графе Zonos еще нет стандартизированного аргумента idempotencyKey во всех мутациях создания, ориентированных на клиентов; это находится в планах разработки. До его выпуска используйте приведенные ниже паттерны, чтобы сделать мутации безопасными для повторения.

Мутации, безопасные по умолчанию 

Некоторые мутации являются естественно идемпотентными, потому что они выполняют операцию upsert по стабильному идентификатору, который вы предоставляете. Когда вы вызываете эти мутации с одинаковыми входными данными, результат одинаков — нет риска создания дубликатов.

• Мутации, которые принимают уникальный идентификатор, предоставленный продавцом (например, externalId заказа), при повторном вызове с теми же параметрами возвращают существующую запись вместо создания новой.
• Операции только для чтения (запросы) всегда безопасны для повторения.

Когда вы можете присоединить свой собственный стабильный идентификатор к создаваемому ресурсу, отдавайте предпочтение этому подходу.

Паттерны для мутаций, которые не являются естественно идемпотентными 

Для мутаций, которые создают ресурсы без ключа, предоставленного продавцом, относитесь к ним как к не более одного раза со своей стороны:

1. Сохраните запрос перед отправкой. Запишите строку в собственную базу данных (статус pending) перед сетевым вызовом.
2. Отправьте мутацию. При успехе запишите возвращаемый идентификатор ресурса в ответ на вашу ожидающую строку (статус committed).
3. При ошибке сети не повторяйте попытку вслепую. Запросите граф Zonos, чтобы определить, был ли создан ресурс (например, перечислив ресурсы, созданные за последние несколько минут для вашей учетной записи, или запросив связанный ресурс, который вы можете соотнести). Повторяйте попытку только если вы можете подтвердить, что ресурс отсутствует.
4. Используйте уникальное ограничение в собственной базе данных для любого бизнес-ключа, который представляет запрос, так чтобы дублирование повторной попытки из вашего собственного приложения не могло привести к двойной отправке.

Доставка вебхуков — как минимум один раз 

Когда вы потребляете вебхуки Zonos, спроектируйте обработчики так, чтобы они были идемпотентными — одно и то же событие может быть доставлено несколько раз. Дедублируйте по идентификатору события. См. Вебхуки для поля идентификатора события.

Куда движется платформа 

Базовая платформа уже запускает потоки с ключами идемпотентности в production для повторных попыток выставления счетов: ключ определяет область повторной попытки и предотвращает дублирующиеся вызовы процессора платежей. Мы работаем над раскрытием того же паттерна в виде дополнительного аргумента idempotencyKey для мутаций создания, ориентированных на клиентов. При предоставлении граф вернет исходный ответ для любого последующего вызова с тем же ключом в пределах окна хранения. Эта страница будет обновлена, когда интерфейс станет общедоступным.

Если стандартизированные ключи идемпотентности для мутаций создания, ориентированных на клиентов, блокируют вашу интеграцию, обратитесь в поддержку.