# Estratégias de Cache

Como mencionado nos conceitos de Planos e Preços, o usuário pode optar em adquirir suas informações em tempo real ou previamente armazenadas em banco de dados.

O intuito desta funcionalidade é reduzir seu consumo de créditos e tempos de resposta da maneira mais eficiente possível sem prejudicar a fidelidade de sua aplicação.

Para os serviços suportados, o controle do cache é feito através dos parâmetros de query strategy, maxAge e maxStale.


# Serviços Suportados

As seguintes consultas possuem a funcionalidade de cache:

Estabelecimentos
/api/data/office/

Receita Federal
/api/portal/rfb/

Simples Nacional
/api/portal/simples/

Cadastro de Contribuintes
/api/portal/ccc/


# Utilização Básica

Para grande parte dos usuários, o comportamento desejado ao realizar uma consulta com suporte a cache se encaixa em um destes cenários:

# Modo Gratuito

"Não quero que meus créditos sejam cobrados em hipótese alguma. Caso os dados não estejam disponíveis retorne um exceção not found (404)"

Neste caso basta adicionar o parâmetro a seguir e o efeito já estará garantido:

strategy=CACHE

# Economia de Créditos

"Minha aplicação aceita dados previamente armazenados desde que mais recentes que X dias."

Obter este resultado em nossa API é muito simples, basta adicionar como parâmetro de query:

maxAge=X

Onde X é o número de dias conforme citação anterior.

# Mitigação de Erros

"Minha aplicação aceita dados previamente armazenados desde que mais recentes que X dias. Caso a consulta online falhe, será aceito dados com idade de até Y dias."

Outro cenário comum, é aceitar dados mais antigos no caso de uma falha. Neste caso, a configuração será:

strategy=CACHE_IF_ERROR&maxAge=X&maxStale=Y

Onde X é o número de dias desejado, e Y o número de dias aceito em caso de erro.


# Utilização Avançada

O controle de cache é manipulado por 3 parâmetros: strategy, maxAge e maxStale.

# Estratégia

  • Parâmetro: strategy
  • Padrão: CACHE_IF_FRESH

Determina a estratégia de aquisição do dado, os valores possíveis são:

  • ONLINE : Consulta a fonte online ignorando qualquer cache. Não recomendado.
  • CACHE_IF_FRESH : Retorna o dado em cache obedecendo à idade máxima fornecida em maxAge, se não, busca na fonte online.
  • CACHE_IF_ERROR : Idem ao CACHE_IF_FRESH, porém se a consulta online falhar, retorna o dado em cache desde que obedeça à idade máxima fornecida em maxStale.
  • CACHE : Retorna o dado mais recente em cache evitando qualquer consulta online, em caso de inexistência resultará em erro 404.

# Idade Máxima

  • Parâmetro: maxAge
  • Padrão: 30D

Controla a idade máxima que um dado em cache é aceite, pode ser utilizado em conjunto com as estratégias CACHE_IF_FRESH ou CACHE_IF_ERROR.

Configure o valor no formato nD, nM ou nY, sendo n variável. Exemplos:

  • 17D : Aceita dado em cache se mais recente que 17 dias.
  • 2M : Aceita dado em cache se mais recente que 2 meses.
  • 1Y : Aceita dado em cache se mais recente que 1 ano.

# Expiração Máxima

  • Parâmetro: maxStale
  • Padrão: 1Y

Na ocasião de uma consulta online falhar, controla a idade máxima que um dado em cache é aceite.

Pode ser utilizado em conjunto apenas com a estratégia CACHE_IF_ERROR, e também considera o valor de maxAge.

Configure o valor no mesmo formato de maxAge, o comportamento irá variar de acordo com ambas propriedades. Exemplos:

  • maxAge=17D&maxStale=1M : Retorna do cache se mais recente que 17 dias, se não, consulta online. Em caso de exceção, retorna do cache se mais recente que 1 mês.
  • maxAge=2M&maxStale=1Y : Retorna do cache se mais recente que 2 meses, se não, consulta online. Em caso de exceção, retorna do cache se mais recente que 1 ano.

Se ocorrer uma exceção durante a consulta online, e o cache obedecer ao intervalo fornecido em maxStale, a consulta retornará com sucesso e a propriedade stale adicionada ao retorno:

{
  "stale": true,
  "updated": "2020-01-01T00:00:00",
  "..."
}