Идемпотентность — свойство операции, которое при повторном вызове позволяет возвращать тот же результат, что и при первом. Таким образом сервер будет возвращать идентичные ответы на идентичные запросы и предотвратит, например, повторное создание кластера.
Чтобы применить свойство идемпотентности, необходимо передать в запросе заголовок Idempotency-Key: <UUID>. Например:
POST /api/v1/{project_id}/clustersIdempotency-Key: 497f6eca-6276-4993-bfeb-53cb********
Когда сервер получит запрос с idempotency_key, он проверит, была ли ранее создана операция с таким UUID. Если операция была выполнена ранее, сервер вернет объект Operation с текущим статусом этой операции. Если операции с таким UUID не найдено, сервис выполнит ее и вернет ответ.
Можно присвоить свой Idempotency-Key в формате UUIDv4 или оставить поле пустым. Тогда сервер сгенерирует UUID и присвоит его операции. Вы можете скопировать его из ответа в параметре idempotency_key.
Рассмотрим пример с созданием кластера Data Platform:
POST /api/v1/{project_id}/clustersIdempotency-Key: 497f6eca-6276-4993-bfeb-53cb********
Соединение прерывается, ответ сервера не успевает дойти. Кластер уже создается, но статус вам неизвестен из-за проблем с сетью. Вы отправляете повторный запрос с тем же Idempotency-Key и получаете ответ, отправленный на предыдущий запрос. Таким образом, если повторно отправить запрос с тем же UUID, сервер не будет создавать новый кластер.