Resumo

  • O RFC 9727 define /.well-known/api-catalog e a relação api-catalog para um publicador declarar um conjunto de APIs. Não certifica propriedade, autorização, disponibilidade, monitoramento nem saúde de cada item.
  • Catálogos na origem, em outro domínio ou aninhados têm autoridades, contextos, caches e ciclos próprios. A topologia é um grafo de afirmações datadas, não uma cadeia automática de confiança.
  • Remover um item comprova alteração da publicação. Aposentadoria segura ainda exige evidência de exposição, tráfego, dependências, execução, reversão e observação posterior.

A ficha muda antes da infraestrutura

Publicado em fevereiro de 2025 no Standards Track do IETF, o RFC 9727 cria um mecanismo compacto. O publicador responde em /.well-known/api-catalog, pode anunciar o catálogo por Link e entrega Linkset JSON. item aponta para APIs; api-catalog aponta para catálogos subordinados.

Isso reduz uma dificuldade real. APIs costumam ficar espalhadas por configurações, gateways, portais e planilhas. Um ponto padronizado transforma memória local em declaração legível por máquinas. Mas declaração não é inventário físico completo.

O RFC 8288 expressa relações tipadas. Um item válido não prova resolução de DNS de uma rede específica, listener ativo, propriedade do destino, credencial aceita nem transação concluída. Uma interface ausente tampouco deixa de escutar.

O OWASP API9:2023 associa versões antigas, hosts não documentados e ambientes mal definidos a uma superfície maior de ataque. O catálogo pode diminuir essa cegueira, desde que seja comparado com o que está exposto. Contar apenas links cria uma falsa certeza mais organizada.

Autoridade não se herda pelo aninhamento

Mesmo no domínio do publicador, um catálogo pode listar parceiro, serviço gerenciado, região ou caminho histórico. A evidência mostra que alguém publicou a relação; não que controle a outra ponta.

O RFC 9727 permite apontar para catálogo em domínio diferente quando não é possível hospedar o recurso well-known. Resposta inicial, redirects, identidades TLS, horários e hash formam então a cadeia de publicação. O título final não basta para demonstrar continuidade de autoridade.

No aninhamento, um catálogo corporativo pode levar a produtos e regiões mantidos por equipes diferentes. O RFC 9264 exige contexto explícito porque um Linkset sem seu anchor pode mudar de sentido. A hierarquia é um grafo de arestas datadas.

Um recibo útil guarda domínio, caminho, redirects, par TLS, horário, tipo de mídia, profile, ETag ou Last-Modified, hash e cada tripla contexto—destino—relação. Primeira e última observações não viram, por conveniência, datas de criação e exclusão. Essa é uma proposta analítica, não requisito novo do RFC.

O cache e a API obedecem a relógios distintos

O RFC 9111 separa frescor, revalidação e respostas antigas. ETag confirma que a representação não mudou entre validações; não confirma continuidade dos serviços listados. Frescor longo pode atrasar uma retirada urgente. Frescor curto aumenta consultas sem corrigir uma origem desatualizada.

É preciso separar intenção editorial, resposta da origem, validação ou reutilização do cache, mudança no gateway e momento da observação. “Não constava às 14h” é verificável com resposta e caminho do cache. Não significa “foi desligada às 14h”.

O próprio RFC recomenda monitorar disponibilidade e desempenho do catálogo, correlacionar consultas com chamadas posteriores, remover itens antigos, validar sintaxe e regras e integrar atualizações ao ciclo de release. Também afirma que o catálogo complementa — não substitui — um framework de gestão de APIs.

Catálogo saudável, item doente

Uma sonda pode baixar, validar e percorrer todos os catálogos enquanto um item falha. A origem do catálogo pode cair enquanto clientes que conhecem o endereço continuam funcionando. A relação status do RFC 8631 localiza informação de estado, mas não transforma catálogo, página de status e transação em uma medida única. Conexão TCP, resposta HTTP e operação autenticada são observações diferentes.

O RFC 9727 também alerta que catálogos podem revelar APIs internas. TLS, revisão, escrita com privilégio mínimo, rate limit e controle de acesso protegem a publicação; não demonstram que uma API interna não esteja exposta. Ler a lista também não dá autorização para usar os destinos.

Retirar do catálogo não aposenta o endpoint

Auditar o catálogo pode revelar APIs zumbis — sem suporte, monitoramento ou correções. Elas existem porque registro administrativo e sistema em execução divergiram. A descoberta abre a investigação; não é certificado de desligamento.

Excluir um item pode corrigir, transferir, ocultar, substituir ou iniciar retirada. Não fecha listener, revoga segredo, apaga DNS, drena fila nem migra cliente desconhecido. Manter o item também não prova suporte.

Um recibo de aposentadoria deve unir última versão e decisão autorizada a mudanças de DNS, roteamento, balanceador e gateway; interfaces e ambientes; responsáveis e tarefas dependentes; tráfego com janela e pontos cegos; credenciais e fluxos; confirmação de execução; responsáveis por exceção e rollback; sondas posteriores. Processo trimestral ou parceiro fora da medição é “desconhecido”, não zero.

O artigo da BTW sobre Deprecation e Sunset já trata da migração do cliente. Aqui, a tese é sobre topologia: uma relação removida não comprova execução. O servidor pode responder depois da exclusão e desaparecer antes da atualização da lista. A divergência deve ficar registrada.

Fontes

Especificações e registros: RFC 9727, RFC Editor, IETF Datatracker, IANA well-known, IANA relações, RFC 9264, RFC 8288, RFC 8615, RFC 8631, RFC 9111, RFC 9745, RFC 8594, OWASP API9:2023.

Referencial atribuído: Lu Heng — Nota 64, primazia do código em execução, por que a BTW registra a realidade.