RFC 9745 e seu impacto na governança de APIs

Introdução

A Internet Engineering Task Force (IETF) – organização internacional aberta que desenvolve e promove padrões técnicos para a internet, como os protocolos TCP/IP, HTTP e DNS – acaba de lançar a RFC 9745, que define uma forma padronizada de se informar a depreciação de recursos no contexto do HTTP, o que é especialmente relevante para APIs baseadas neste protocolo.

Em resumo, a partir de agora, servidores podem informar seus clientes sobre o status de depreciação de determinados recursos utilizando o cabeçalho de resposta Deprecation, cujo valor é uma data, no passado ou futuro, indicando que o recurso já foi ou ainda será depreciado. Adicionalmente, é possível utilizar o cabeçalho Link para apontar uma documentação e, também, o Sunset, trazendo a data na qual o recurso se tornará indisponível.

Neste artigo iremos avaliar a viabilidade de se aplicar este padrão no mundo real. Utilizando as melhores práticas no desenvolvimento de APIs, partiremos de arquivos de definição que seguem a OpenAPI Specification e terminaremos no API gateway KrakenD.

Impactos

Como dito, este novo padrão é especialmente importante para as webs APIs, ou seja, para as APIs que aderem ao protocolo HTTP, como as famosas REST. Neste contexto, a RFC oferece meios de se levar as políticas de depreciação — outrora restritas à documentação ou ao design time — ao tempo de execução.

Portanto, a novidade tem o potencial de seriamente mitigar as quebras de integração, possibilitando aos desenvolvedores realizarem as adaptações necessárias com uma antecedência confortável. Aliás, vale lembrar que estamos entrando na era da A.I. (com seus agentes, servidores MCP e etc.), o que só faz aumentar o impacto deste novo padrão, já que eles podem aprender e se adaptar sozinhos diante da sinalização de depreciação.

No contexto de governança, a RFC também torna possível aos fornecedores de gateways de API (como Kong, Tyk, KrakenD, Traefik, APISix e etc.) considerarem o novo padrão durante os processos automatizados de deploy de APIs, sobretudo quando pensamos em APIOps baseado em OpenAPI specification. Vejamos.

A especificação OpenAPI prevê a indicação de depreciação de operações através do campo deprecated. Com esta nova RFC, é simplesmente natural pensarmos em linkar as coisas, ou seja, fazer com que a indicação de depreciação presente nos arquivos de definição encontre correspondência na configuração dos gateways, que, uma vez em execução, passem a injetar o novo cabeçalho de resposta nas operações apropriadas. Esta melhoria levaria a governança ao próximo nível de qualidade!

Provando o conceito

Utilizaremos o arquivo de definição aderentes à OpenAPI Specification (OAS) para descrever nossa API, construiremos um parser em Go utilizando a libopenapi, contaremos com o KrakenD como API gateway e um HttpBin como backend.

Todos os detalhes do projeto podem ser encontrados neste repositório. Então, vou destacar apenas os pontos principais:

O arquivo de definição (openapi.yaml)

paths:
(…)
/users/{userId}:
    (…)
    delete:
      (…)
      xdeprecated: true

Observe que a operação de deleção de usuário conta com o campo padrão da OAS deprecated com o valor true. Bem, é fácil perceber que estamos diante de uma incompatibilidade de impedância quando tentamos fazer esse booleano interagir com os novos cabeçalhos previstos na RFC 9745, já que estes são muito mais ricos em informação do que aquele.

Por razões como esta, a OAS possui extensões, que, no nosso caso, serão utilizadas para descrever as propriedades esperadas pela RFC da seguinte forma:

paths:
(…)
/users/{userId}:
    (…)
    delete:
      (…)

      deprecated: true
      x-deprecated-at: “2025-06-30T23:59:59Z”
      x-deprecated-sunset: “2026-01-01T00:00:00Z”
      x-deprecated-link: https://api.example.com/deprecation-policy

O Parser

A função do parser é ler e interpretar o arquivo de definição openapi.yaml, extrair as informações relevantes para o gateway, e criar o arquivo operations.json, que será embarcado na imagem do KrakenD e consumido durante a sua inicialização, numa abordagem denominada configuração flexível.

Este é o resultado do operations.json:

{

“list”: [

{

“path”: “/users”,

“method”: “get”,

“backend”: {

“path”: “/users”,

“host”: “http://backend:8888”

}

{

“path”: “/users”,

“method”: “post”,

“backend”: {

“path”: “/users”,

“host”: “http://backend:8888”

}

{

“path”: “/users/{userId}”,

“method”: “get”,

“backend”: {

“path”: “/users/{userId}”,

“host”: “http://backend:8888”

}

{

“path”: “/users/{userId}”,

“method”: “delete”,

“deprecated”: {

“at”: “@1751327999”,

“link”: “https://api.example.com/deprecation-policy”,

“sunset”: “Thu, 01 Jan 2026 00:00:00 UTC”

“backend”: {

“path”: “/users/{userId}”,

“host”: “http://backend:8888”

}

]

}

Observe que o parser projetou os elementos estendidos da OAS no arquivo de configuração do KrakenD, inclusive fazendo as devidas conversões de valores, da seguinte forma:

OAS                                KrakenD
x-deprecated-at:                   deprecated.at:
x-deprecated-link:                 deprecated.link:
x-deprecated-sunset:               deprecated.sunset:

O plugin

Agora que a configuração do gateway foi devidamente gerada a partir do arquivo de definição, nosso plugin personalizado entra em cena. A sua função é identificar as operações de api depreciadas e inserir os cabeçalhos da RFC 9745 com os valores adequados.

Mais detalhes podem ser encontrados no repositório do artigo. Mas, uma vez que o plugin foi embarcado no KrakenD, temos os seguintes resultados:

GET /users/1

DELETE /users/1

Observe que apenas a segunda operação estava depreciada (vide operations.json) e o gateway adicionou corretamente os cabeçalhos na resposta.

Conclusões

O experimento mostrou a viabilidade do conceito, ou seja, que é possível levar as políticas de depreciação para além da definição e documentação, sendo facilmente comunicadas em tempo de execução. Desta forma, os sistemas podem adotar ações automatizadas para comunicar a obsolescência aos interessados e reduzir significativamente as chances de falhas nas integrações.

Embora as extensões da OpenAPI Specification tenham tornado isso possível diante da insuficiência do booleano deprecated, imagino que a OpenAPI Initiative deve incluir uma melhoria nas próximas versões. Sobretudo quando penso que Eric Wilde, co-autor desta RFC, é bem atuante no mundo das APIs.

Aos leitores que chegaram até aqui, meu muito obrigado. Espero que estas poucas palavras lhes tenham acrescentado algo e feito o seu tempo valer a pena.

Até a próxima!

Link relevantes: