Saltar 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 desenvolve não mude debaixo dos seus pés. As versões datadas são a fronteira grossa para alterações incompatíveis; dentro de uma versão o schema continua a evoluir apenas por adição.

Nomes das versões​

Uma versão chama-se 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 apenas quando existe uma alteração incompatível — os trimestres sem alterações deste tipo são saltados, pelo que as versões são relativamente raras.

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

Selecionar uma versão​

Duas formas, por ordem de precedência:

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

Se omitir a versão — ou indicar uma desconhecida ou já para lá da data de descontinuação — o pedido é servido pela versão mais antiga ainda suportada, nunca pela mais recente. Nunca é migrado em silêncio para uma alteração incompatível. Fixe uma versão explicitamente em qualquer integração que tencione manter.

Cada resposta indica a versão que a serviu num cabeçalho X-Api-Version, pelo que sabe sempre que contrato respondeu — e deteta desvios caso se tenha apoiado no comportamento por omissão.

Período de suporte​

Cada versão estável é suportada durante pelo menos 12 meses, com pelo menos 9 meses de sobreposição com a seguinte. Na prática, duas a três versões estão ativas em qualquer momento, o que dá uma janela confortável para migrar. A data de descontinuação de uma versão é publicada no dia em que esta é lançada.

O que conta como alteração incompatível​

Dentro da mesma versão podemos fazer alterações por adição, e o seu cliente tem de as tolerar:

  • 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 (por isso, nunca assuma que um enum está fechado).

Uma nova versão datada está reservada a alterações verdadeiramente incompatíveis: remover ou renomear um campo ou tipo, endurecer a nulabilidade, ou alterar o significado de um argumento ou de um valor por omissão. Estas nunca acontecem dentro de uma versão existente — a versão que fixou mantém o seu comportamento até à data de descontinuação.

Descontinuações​

As descontinuações são sinalizadas de duas formas, para que tome conhecimento delas antes que algo deixe de funcionar:

  • No schema. Um campo em vias de ser retirado é marcado com @deprecated e um motivo que nomeia o seu substituto. A introspeção e o GraphQL Playground mostram isto automaticamente a qualquer cliente.
  • Na resposta. Quando um pedido resolve efetivamente um campo descontinuado, a resposta traz o cabeçalho X-Api-Deprecated-Reason (e uma entrada extensions.deprecations correspondente) a nomear as descontinuações concretas que tocou — assim, uma descontinuação aparece nos seus registos no momento em que a encontra, sem ter de a ir procurar.

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