Saltar para o conteúdo principal

Operações de escrita que alteram um recurso existente

Não envolve qualquer cabeçalho. Onde antes uma repetição devolvia um erro, agora devolve o estado atual: Uma repetição não escreve nada e a sua resposta inclui Idempotent-Replayed: true — esse cabeçalho permite-te distinguir “eu cancelei-o” de “já estava cancelado”. Três exceções devolvem 409 em vez disso:
  • Ativar com um activated_at diferente. A hora de colheita é a que consta no relatório laboratorial, pelo que uma nova tentativa não deve substituí-la silenciosamente.
  • Cancelar uma marcação já cancelada com um cancellation_reason diferente. O mesmo raciocínio: o motivo registado pode entretanto ter sido corrigido e uma nova tentativa não deve substituí-lo. Volta a enviar o motivo registado ou omite-o.
  • Cancelar após o ponto sem retorno — uma colheita de sangue confirmada, um envio recolhido, um kit expedido ou ativado.
Três endpoints não são deliberadamente seguros para repetição:

Operações de escrita que criam algo

Cinco endpoints aceitam um cabeçalho Idempotency-Key opcional, com no máximo 255 caracteres: Uma chave, quatro tentativas, uma encomenda — o que recebes depende de quando voltas a tentar e de o corpo coincidir ou não: Diagrama de sequência: um pedido duplicado disparado 350 ms após o primeiro recebe 409 enquanto esse pedido ainda está em execução, o primeiro devolve 201, uma nova tentativa posterior com a mesma chave devolve a mesma encomenda marcada como Idempotent-Replayed e a mesma chave com o corpo alterado devolve 409. Diagrama de sequência: um pedido duplicado disparado 350 ms após o primeiro recebe 409 enquanto esse pedido ainda está em execução, o primeiro devolve 201, uma nova tentativa posterior com a mesma chave devolve a mesma encomenda marcada como Idempotent-Replayed e a mesma chave com o corpo alterado devolve 409. As chaves estão associadas à tua chave API e ao endpoint, pelo que nunca colidem com as de outro parceiro nem com a mesma chave usada noutro local.
  • Mesma chave, mesmo corpo → durante 24 horas recebes de volta a resposta original, marcada com Idempotent-Replayed: true. A ordem dos campos e os espaços em branco não importam.
  • Mesma chave, corpo diferente → 409.
  • Um Idempotency-Key vazio → 400, em vez de ser ignorado.

Quando a chave é libertada

A criação não é atómica — um 5xx não significa que nada foi escrito.
  • O pedido falhou antes de algo ser criado → a chave é libertada, pelo que podes voltar a tentar com ela.
  • O pedido falhou depois de algo ser criado, ou nunca devolveu resposta → a chave permanece ocupada e as novas tentativas recebem 409. Obtém o recurso para verificar se existe e depois usa uma nova chave se não existir.
Uma repetição devolve o corpo da resposta registado quando o recurso foi criado — um snapshot, não uma leitura em tempo real. Se o recurso mudou entretanto, obtém-no diretamente.

Algumas criações também têm uma chave natural

Dois endpoints rejeitam duplicados por conta própria, independentemente de qualquer cabeçalho:
  • Criar marcação permite uma marcação por perfil, local e instante. Uma repetição devolve 409 com o appointment_id existente.
  • Criar perfil devolve 409 quando email já tem um perfil. Omite email e é gerado um placeholder único por pedido, pelo que as repetições criam mesmo perfis separados.
Quando ambos se aplicam, vês o 409 da chave natural e só ele inclui o campo extra (appointment_id ou um discriminador error_name) — um 409 de idempotência traz apenas error, pelo que deves ler esses campos de forma defensiva.