Revisões e reversão

Reverter é voltar a servir uma revisão anterior. Não é "desfazer no banco": é uma operação completa, com a mesma verificação da publicação.

O que é uma revisão

Cada publicação bem-sucedida cria uma revisão imutável, numerada em sequência por API, com o snapshot compilado da configuração e o digest. A revisão guarda:

• rotas;
• backends;
• política de segurança;
• política de tráfego.

Não fazem parte da revisão (portanto não "voltam" com a reversão):

• consumidores, chaves e autorizações;
• endereços próprios e certificados;
• estado da organização (suspensa ou ativa).

Ou seja: reverter uma API não desfaz uma revogação de chave nem remove um domínio adicionado depois. Se o incidente envolveu credencial vazada, a reversão não é a resposta — revogar a chave é.

Consultar

Recurso	O que devolve
GET /v1/apis/{apiId}/revisions	a lista de revisões, sem o snapshot
GET /v1/apis/{apiId}/revisions/{revisionId}	a revisão com o snapshot compilado completo

Reverter

curl -sS -X POST "$BASE/v1/apis/$API_ID/rollback" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: rollback-para-revisao-3' \
  -d '{"revision_id":"0192f3a4-3333-7000-8000-000000000003"}'

A resposta é 202 com a operação (tipo ROLLBACK). Acompanhe como qualquer publicação.

O que a reversão faz

Passa pelos mesmos passos de uma publicação, com o snapshot da revisão escolhida:

PENDING → VALIDATING → APPLYING → VERIFYING → SMOKE_TESTING → SUCCEEDED

Isso significa que reverter também:

• revalida os backends da revisão antiga — eles precisam continuar permitidos hoje. Um backend que virou endereço privado desde então impede a reversão (publish_validation_failed). É deliberado: a política de destino vale para o que está no ar, não apenas para o que é novo;
• confirma a configuração em cada máquina do gateway;
• executa o teste de fumaça.

Uma reversão que só trocasse um ponteiro no banco deixaria a API num estado que o produto não consegue provar — e é justamente o que este desenho evita.

Regras

Regra	Consequência
A revisão precisa existir	404 revision_not_found
A revisão precisa ser da mesma API	senão 404 revision_not_found
A revisão precisa ter backends ainda permitidos	senão 422 publish_validation_failed
Não pode haver outra operação em curso	409 operation_in_progress
Reverter para a revisão já publicada	409 nothing_to_publish
Idempotency-Key	repetir devolve a mesma operação

Reversão, desativação e rascunho

Preciso…	Use
voltar ao comportamento de ontem, mantendo a API no ar	reverter para a revisão de ontem
tirar a API do ar agora	POST /disable
voltar ao ar depois de desativar	POST /enable (reaplica a revisão publicada)
descartar alterações do rascunho (que nunca foram publicadas)	basta não publicar; o rascunho não afeta o tráfego

O rascunho não é alterado pela reversão: ele continua como está. Resultado: depois de reverter, has_unpublished_changes normalmente fica true, porque o rascunho difere da revisão que voltou a valer.

Para "sincronizar" de vez, existem dois caminhos:

1. publicar o rascunho (volta ao estado novo), ou
2. ajustar o rascunho manualmente para refletir a revisão desejada.

Não há hoje um endpoint que restaure o rascunho a partir de uma revisão.

Roteiro de incidente com reversão

1. Identifique a última revisão boa: GET /v1/apis/{apiId}/revisions.
2. Reverta com Idempotency-Key (para poder repetir sem duplicar).
3. Acompanhe até SUCCEEDED — não anuncie "revertido" antes disso.
4. Confirme com GET /v1/apis/{apiId}/status e com um GET /__nn/ping (cabeçalho X-NN-Revision).
5. Registre o incidente internamente.

Cada reversão bem-sucedida gera auditoria API_ROLLED_BACK, com a revisão de origem e o solicitante. Falhas geram API_PUBLISH_FAILED com o código de erro. A trilha é consultável pela Console.

Próximos passos

• Publicação: as etapas que a reversão repete.
• APIs: ciclo de vida e alterações não publicadas.
• Erros e diagnóstico: revision_not_found e nothing_to_publish.