Versionamento da API Apolônia Grade

A API pública do catálogo usa versão maior no caminho: https://apoloniarosadodeserto.com.br/apps/catalogo/v1. A versão v1 está ativa. O contrato OpenAPI versionado fica em https://apoloniarosadodeserto.com.br/apps/catalogo/v1/openapi.json; o endereço anterior https://apoloniarosadodeserto.com.br/apps/catalogo/openapi.json continua disponível e descreve essa mesma versão.

Compatibilidade

GET https://apoloniarosadodeserto.com.br/apps/catalogo/v1/products pesquisa produtos publicados. GET https://apoloniarosadodeserto.com.br/apps/catalogo/v1/products/{handle} consulta um produto. Os caminhos anteriores /products e /products/{handle}, sem /v1, continuam ativos como aliases da v1: mesmo formato de dados, parâmetros, validações e erros, sem redirecionamento. Não passam automaticamente para uma futura v2. Clientes atuais não precisam ser alterados.

Evolução

Campos opcionais podem ser acrescentados sem remover os existentes. Remover ou renomear campos, mudar tipos ou alterar o significado de parâmetros exige uma nova versão maior em outro caminho. Os consumidores devem ignorar campos adicionais que não utilizam. O cabeçalho informativo API-Version: 1 identifica o contrato atual e não é um mecanismo de negociação.

Descontinuação

Não existe descontinuação ou data de encerramento programada para a v1 nem para seus aliases. Por isso não emitimos cabeçalhos Deprecation ou Sunset com datas fictícias. Antes de retirar uma versão, a documentação publicará o substituto, as alterações e o guia de migração. Quando houver uma descontinuação efetiva, as respostas afetadas usarão Deprecation conforme RFC 9745; se houver data definida de desligamento, também usarão Sunset conforme RFC 8594. O Link com rel="deprecation" aponta para esta política mesmo enquanto a API continua ativa.

Limites de escopo

A política aplica-se somente a esta API REST pública. O MCP em https://apoloniarosadodeserto.com.br/apps/catalogo/mcp negocia sua versão pelo protocolo MCP. As APIs nativas Shopify e UCP são controladas pela plataforma, não por esta política. Nenhuma versão permite leitura de clientes ou pedidos, escrita, carrinho ou pagamento. Preços e disponibilidade são atuais e devem ser confirmados no checkout oficial.