Publicação

Publicar é o ato de tornar a configuração atual (o rascunho) a configuração que está servindo. Só depois de publicar as alterações passam a valer no tráfego.

Publicar não é um clique otimista: a operação passa por etapas verificáveis e só termina em SUCCEEDED quando todas as máquinas do gateway confirmaram a mesma configuração e responderam ao teste de fumaça.

O que a publicação faz

1. Valida o rascunho: existe ao menos uma rota habilitada, toda rota tem métodos e backend existente, os parâmetros usados no caminho de backend existem no caminho público, todo backend continua permitido pela política de destino (o DNS é reavaliado), o TLS está coerente e a configuração de JWT está completa (issuer e discovery em https, pelo menos uma audiência, exatamente um algoritmo). O host do issuer e do discovery passa pela mesma política anti-SSRF aplicada ao backend, porque é o data plane que busca o documento de descoberta e as chaves.
2. Cria a revisão — foto imutável, com resumo digital — e a operação, na mesma transação. Resposta: 202 com o identificador da operação.
3. Um processo interno aplica a revisão no runtime.
4. Verifica em cada máquina que o objeto está presente e com a versão aplicada.
5. Faz o teste de fumaça em cada máquina: GET /__nn/ping no endereço da API, exigindo o cabeçalho X-NN-Revision com o número da revisão publicada.

Consequência prática: o 202 significa "aceito e em execução", não "no ar". Acompanhe a operação.

Acompanhar a operação

curl -sS "$BASE/v1/apis/$API_ID/deployments/$OPERATION_ID" \
  -H "Authorization: Bearer $TOKEN"

Estado	Significado
PENDING	na fila
VALIDATING	revalidando a configuração (inclusive DNS dos backends)
APPLYING	gravando a configuração no runtime
VERIFYING	conferindo cada máquina (prazo de 30 s)
SMOKE_TESTING	testando o endereço em cada máquina (prazo de 30 s)
SUCCEEDED	no ar, confirmado
FAILED	falhou; se havia revisão anterior, ela voltou a valer
CANCELLED	cancelada

Tipos de operação: PUBLISH, ROLLBACK, DISABLE, ENABLE e DELETE.

Se falhar

A falha é segura: o produto reaplica a revisão anterior, e a API continua atendendo na última configuração válida (ou fica FAILED, se nunca houve uma publicação bem-sucedida).

A operação carrega error_code e error_message:

error_code	Significado	Ação
publish_validation_failed	a configuração não passou na validação	veja details.problems na resposta do POST
runtime_rejected_configuration	o runtime recusou a configuração	corrija a configuração; se persistir, abra incidente
runtime_unavailable	o runtime não respondeu	repita; se persistir, abra incidente
propagation_not_confirmed	alguma máquina não confirmou a versão no prazo	repita (a operação é idempotente)
smoke_test_failed	o endereço não respondeu ao teste de fumaça	verifique se o endereço resolve para o gateway e repita

Por que uma revisão por vez

• Uma operação por API: se alguém publicar enquanto outra publicação está em curso, a segunda recebe 409 operation_in_progress.
• If-Match: se você enviar o If-Match com o draft_version que leu, o produto recusa publicar um rascunho diferente do que você viu (412 precondition_failed).
• Idempotency-Key: repetir a chamada com a mesma chave devolve a mesma operação, sem criar outra. Use quando houver timeout de rede.
• Nada a publicar: se o resumo do rascunho é igual ao da revisão ativa, a resposta é 409 nothing_to_publish.

Revisões

Cada publicação bem-sucedida cria uma revisão imutável, numerada em sequência por API, com o snapshot compilado e o digest. Você pode listar e consultar:

Recurso	O que devolve
GET /v1/apis/{apiId}/revisions	lista (sem o snapshot)
GET /v1/apis/{apiId}/revisions/{revisionId}	a revisão com o snapshot compilado completo

Republicar o mesmo rascunho depois de uma falha reaproveita a revisão de mesmo digest — não cria número novo. Detalhes de reversão em Revisões e reversão.

O que a publicação não afeta

Mudanças nestes itens aplicam direto, sem publicação, porque não fazem parte da revisão:

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

Publicar, desativar e reativar

Ação	Efeito
POST /v1/apis/{apiId}/publish	publica o rascunho atual
POST /v1/apis/{apiId}/disable	remove a API do runtime e aguarda a ausência em todas as máquinas; lifecycle = DISABLED
POST /v1/apis/{apiId}/enable	reaplica a revisão publicada, com verificação e teste de fumaça

Desativar não apaga nada: a revisão continua lá, e reativar é a mesma revisão voltando ao ar. enable numa API que não está desativada responde 409 com reason = api_not_disabled.

Verificando por fora

• GET /v1/apis/{apiId}/status — estado de publicação, alterações não publicadas, a operação ativa e a última, o resumo do runtime e a saúde observada (gateway por réplica, backends por alvo e réplica, certificados).
• GET /__nn/ping no endereço da API — devolve 204 com X-NN-Revision e a revisão no ar. É uma rota de plataforma sem autenticação, sem dado algum.

Limites

Item	Valor
Prazo de verificação por réplica	30 s
Prazo do teste de fumaça	30 s
Prazo de aplicação	60 s
Operações simultâneas por API	1

Próximos passos

• Revisões e reversão: voltar a uma revisão anterior com segurança.
• Visão geral da API: os blocos do status.
• Erros e diagnóstico: publish_validation_failed e os demais códigos.