Mini site de documentaçãoDeveloper Atlas

Entrada rápida para navegar arquitetura, APIs, operação e guias técnicos do projeto sem depender da estrutura do repositório.

53 notas

Procure por módulo, API, rota, fluxo operacional ou termo do projeto.

Guias técnicos/docs/guias/api-publica-v1-e-cache

API Pública v1 e Cache

Esta camada existe para separar leitura pública do runtime administrativo.

Recorte da seçãoGuia orientado por fluxo

Leitura pensada para explicar responsabilidades, ordem de execução e trechos reais do código com foco no fluxo da implementação.

Atualizado15 de abr. de 2026
Seções12
Tags4
guiaapicachemobile

Objetivo

Esta camada existe para separar leitura pública do runtime administrativo.

Ela foi aberta para atender três frentes ao mesmo tempo:

  • storefront consumindo snapshots rápidos;
  • integrações externas sem depender de rotas internas do painel;
  • futura base de leitura para aplicativo mobile.

Endpoints atuais

  • GET /api/v1
  • GET /api/v1/content/pages
  • GET /api/v1/content/pages/[...slug]
  • GET /api/v1/content/blog/posts
  • GET /api/v1/content/blog/posts/[slug]
  • GET /api/v1/catalog/products
  • GET /api/v1/catalog/products/[slug]
  • GET /api/v1/catalog/categories
  • GET /api/v1/catalog/collections
  • GET /api/v1/orders/[publicToken]
  • GET /api/v1/system/health

Envelope

Todas as respostas seguem a mesma base:

json
{
  "version": "v1",
  "generatedAt": "2026-03-18T03:00:00.000Z",
  "data": {},
  "meta": {}
}

Isso facilita troca futura do backend sem quebrar clientes que já dependem da borda pública.

Cache

As rotas públicas são force-dynamic no Next para ler o runtime atual, mas respondem com Cache-Control para permitir cache HTTP fora da aplicação.

Política atual:

  • padrão: public, max-age=60, s-maxage=300, stale-while-revalidate=600
  • erro curto: public, max-age=30, s-maxage=60, stale-while-revalidate=120

Isso mantém a leitura leve para alto volume sem congelar o painel administrativo.

Como a camada lê dados hoje

Conteúdo dinâmico

  • lê site-pages.published.json
  • resolve por slug
  • nunca consulta os documentos administrativos

Blog

  • lê posts-index.published.json
  • lê posts/<slug>.published.json
  • comentários e reações ficam em documentos separados
  • usa o catálogo mock consolidado já disponível no projeto
  • transforma o dado interno em contrato público estável

Hoje já entrega:

  • produtos;
  • categorias;
  • coleções.

Pedidos públicos

  • não expõe dados pessoais;
  • não expõe payload completo do checkout;
  • entrega apenas rastreio resumido por publicToken.

Health

  • resume consistência entre admin e runtime
  • expõe storage publicado, snapshots e override da home

Relação com a futura migração para banco

Esta API foi desenhada para continuar válida quando a persistência sair de JSON e for para banco.

O plano é trocar a origem por projeções de leitura, mantendo:

  • rotas;
  • envelope;
  • filtros principais;
  • política de cache.

Leitura seguinte