Pular para o conteúdo principal

Versionamento da API

A API pública usa versões datadas, o mesmo esquema do Shopify, para que a versão sobre a qual você desenvolve não mude sob seus pés. As versões datadas são a fronteira grossa para mudanças incompatíveis; dentro de uma versão o schema continua evoluindo apenas por adição.

Nomes das versões​

Uma versão se chama YYYY-MM, em que o mês é o início de um trimestre: 2026-01, 2026-04, 2026-07, 2026-10. Uma nova versão datada é lançada somente quando há uma mudança incompatível — trimestres sem mudanças desse tipo são pulados, então as versões são relativamente raras.

Existe também uma versão unstable, que acompanha o estado mais recente do desenvolvimento e permite prever mudanças antes de um lançamento estável. Não construa integrações de produção sobre ela.

Selecionar uma versão​

Duas formas, em ordem de precedência:

  1. Caminho na URL (recomendado): coloque a versão no endpoint — …/backend/<subdomain>/api/2026-07/graphql. É explícito, amigável ao cache e fácil de copiar e colar.
  2. Cabeçalho da requisição: envie X-Api-Version: 2026-07 para o endpoint simples …/backend/<subdomain>/graphql.

Se você omitir a versão — ou indicar uma desconhecida ou já além da data de encerramento — a requisição é atendida pela versão mais antiga ainda suportada, nunca pela mais recente. Você nunca é atualizado silenciosamente para uma mudança incompatível. Fixe uma versão explicitamente em qualquer integração que pretenda manter.

Toda resposta informa a versão que a atendeu em um cabeçalho X-Api-Version, então você sempre sabe qual contrato respondeu — e detecta desvios caso tenha dependido do comportamento padrão.

Período de suporte​

Cada versão estável é suportada por no mínimo 12 meses, com no mínimo 9 meses de sobreposição com a seguinte. Na prática, duas ou três versões ficam ativas a qualquer momento, o que dá uma janela confortável para migrar. A data de encerramento de uma versão é publicada no dia em que ela é lançada.

O que conta como mudança incompatível​

Dentro de uma mesma versão podemos fazer mudanças aditivas, e o seu cliente deve tolerá-las:

  • adicionar um novo tipo, query ou mutation;
  • adicionar um argumento opcional a um campo existente;
  • adicionar um campo a um tipo de objeto;
  • adicionar um valor a um enum (portanto, nunca presuma que um enum é fechado).

Uma nova versão datada é reservada a mudanças genuinamente incompatíveis: remover ou renomear um campo ou tipo, endurecer a nulabilidade, ou mudar o significado de um argumento ou de um valor padrão. Isso nunca acontece dentro de uma versão existente — a versão que você fixou mantém seu comportamento até a data de encerramento.

Descontinuações​

As descontinuações são sinalizadas de duas formas, para que você saiba delas antes que algo quebre:

  • No schema. Um campo em processo de remoção é marcado com @deprecated e um motivo que nomeia o substituto. A introspecção e o GraphQL Playground mostram isso automaticamente a qualquer cliente.
  • Na resposta. Quando uma requisição de fato resolve um campo descontinuado, a resposta carrega o cabeçalho X-Api-Deprecated-Reason (e uma entrada extensions.deprecations correspondente) nomeando as descontinuações específicas que ela tocou — assim, uma descontinuação aparece nos seus logs no momento em que você a encontra, sem precisar procurá-la.

Um campo descontinuado é mantido por um período mínimo publicado antes de ser removido em uma versão datada posterior.