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:

AmbienteURL
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

  1. Anúncio: Campo é marcado com @deprecated(reason: "Use newField")
  2. Período de Migração: Campo antigo e novo coexistem (mínimo 90 dias)
  3. Monitoramento: Uso do campo antigo é monitorado via logging
  4. 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:

HeaderTipoDescrição
X-API-VersionStringVersã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:

  1. Novo campo categories é adicionado ao tipo Product
  2. Campo groups é marcado: @deprecated(reason: "Use categories")
  3. Ambos retornam os mesmos dados por 90 dias
  4. 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 } } }"}'