GUIA

Versionamento

Como a Storefront API evolui sem quebrar integrações existentes.

Filosofia

A Storefront API segue a prática recomendada pelo GraphQL: evolução de schema em vez de versionamento por URL. Isso significa que novas funcionalidades são adicionadas de forma aditiva e campos antigos são marcados como @deprecated antes de serem removidos.

Endpoint

O endpoint da API é fixo:

Ambiente	URL
Produção	`/graphql`

A URL não contém número de versão. O versionamento é feito via header X-API-Version e evolução de schema.

Tipos de Mudança

Mudanças Não-Quebrantes (sempre seguras)

Adicionar novos campos a tipos existentes
Adicionar novos tipos e enums
Adicionar novos argumentos opcionais
Adicionar novas queries e mutations
Marcar campos como @deprecated

Mudanças Quebrantes (requerem migração)

Remover campos (apenas após período de deprecation)
Alterar o tipo de um campo
Renomear campos (tratado como deprecation + novo campo)
Tornar argumentos opcionais obrigatórios

Ciclo de Deprecation

Anúncio: Campo é marcado com @deprecated(reason: "Use newField")
Período de Migração: Campo antigo e novo coexistem (mínimo 90 dias)
Monitoramento: Uso do campo antigo é monitorado via logging
Remoção: Campo é removido quando uso chega a zero ou após aviso final

Header X-API-Version

Para mudanças de comportamento que não podem ser expressas apenas no schema, a API aceita o header X-API-Version. Isso permite que clientes optem por comportamentos específicos:

Header	Tipo	Descrição
X-API-Version	String	Versão do comportamento desejado (ex: `2026-06-01`). Formato date-based.

Se o header não for enviado, a API usa o comportamento padrão (mais recente). O formato date-based evita problemas com versionamento semântico (1.1, 1.2) e deixa claro quando a versão foi introduzida.

Quando usar: Na maioria dos casos, você não precisa enviar esse header. Ele só é relevante quando o changelog da API indica uma mudança de comportamento que requer opt-in.

Exemplo de Evolução

Considere a migração de groups para categories:

Novo campo categories é adicionado ao tipo Product
Campo groups é marcado: @deprecated(reason: "Use categories")
Ambos retornam os mesmos dados por 90 dias
Após monitoramento, groups é removido

Introspection

Use a query de introspection para descobrir campos deprecated no schema:

Header X-API-Version

JavaScript

const response = await fetch(
  '/graphql',
  {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Version': '2026-06-01'
    },
    body: JSON.stringify({
      query: `query { client(hostname: "minha-loja") { store { name } } }`
    })
  }
);

Listar Campos Deprecated

GraphQL

query IntrospectDeprecated {
  __type(name: "Product") {
    fields(includeDeprecated: true) {
      name
      isDeprecated
      deprecationReason
    }
  }
}

Resposta

JSON

{
  "data": {
    "__type": {
      "fields": [
        { "name": "title", "isDeprecated": false, "deprecationReason": null },
        { "name": "categories", "isDeprecated": false, "deprecationReason": null },
        { "name": "groups", "isDeprecated": true, "deprecationReason": "Use categories" }
      ]
    }
  }
}

cURL com X-API-Version

Bash

curl -X POST https://minha-loja.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2026-06-01" \
  -d '{"query":"query { client(hostname: \"minha-loja\") { store { name } } }"}'