Skip to main content
Para as informações mais atualizadas sobre versões históricas da X Ads API, consulte as informações abaixo.

​
Visão geral

Todo mês, fazemos mudanças e lançamos vários novos recursos na X Ads API. Essas mudanças são quase sempre retrocompatíveis, no entanto, tendemos a ter algumas mudanças disruptivas por ano. Recebemos feedback dos desenvolvedores sobre os desafios que nossa cadência rápida de mudanças na Ads API traz para seus ciclos de desenvolvimento quando se trata de implementar novos recursos, lidar com depreciações e testar mudanças. Queremos melhorar a experiência do desenvolvedor usando nossa plataforma Ads, e é por isso que introduzimos o conceito de versionar nossos endpoints. Algumas definições dos conceitos que discutimos: Versão: Refere-se ao número da versão encontrado no path da URL de qualquer requisição da Ads API, por exemplo: GET //accounts. Este estilo de versionamento é conhecido como URI versioning. Mudanças disruptivas (Breaking Changes): Mudanças disruptivas são quaisquer alterações que exigem recursos do desenvolvedor para manter a funcionalidade existente. Isso inclui recursos usados para investigação sobre as mudanças que precisam ser feitas, determinação de features/endpoints sendo depreciados e implementação final de todas essas mudanças. Uma lista de mudanças disruptivas inclui coisas como:
  • Remover um param da requisição/resposta da API
  • Modificar o nome de qualquer param ou endpoint
  • Mudança na representação de valores (preview_url → card_uri)
  • Mudança no comportamento de endpoints (por exemplo, async vs sync stats)
  • Adicionar/mudar params opcionais ou obrigatórios (por exemplo, tornar name um campo obrigatório na requisição)
Depreciação: Versões ou produtos depreciados não terão suporte e recomenda-se que os desenvolvedores deixem de usar essas APIs. Sunset: Uma vez que um produto ou API é descontinuado, o conjunto correspondente de endpoints não estará mais acessível via API.

​
Estratégia de versionamento

Os principais princípios da estratégia são:
  1. Todas as mudanças disruptivas serão agrupadas em uma nova versão
  2. A depreciação de versões existentes sempre que uma nova versão é anunciada é de 6 meses
  3. A qualquer momento, a API permitirá requisições de duas versões simultaneamente, mas a mais antiga das duas não terá suporte
  4. Para permitir a adoção mais rápida de novos produtos, estes serão lançados de forma contínua (fora da cadência de versionamento)
  5. Todas as respostas da API conterão um x-current-api-version que será definido como a versão atual da API, além de um header x-api-warn ao chamar qualquer endpoint depreciado da API.
Caso haja alterações fundamentais em requisitos de produto que exijam uma mudança disruptiva na API (por exemplo, depreciar múltiplas segmentações de faixas etárias), enviaremos um aviso de 90 dias para anunciar essa mudança disruptiva, e após pelo menos 90 dias após o aviso ser divulgado, a mudança disruptiva será implantada. Para os detalhes completos do histórico de versionamento (v0 a v12), incluindo mudanças específicas em cada versão, consulte a versão em inglês em /x-ads-api/fundamentals/versioning. Os anúncios oficiais no Developer Forum permanecem como fontes canônicas.