Pular para o conteúdo principal

Boas práticas

Estas recomendações ajudam a manter a sua integração segura, rápida e estável.

Proteja o seu token​

Consulte a API pelo servidor do seu site, nunca direto do navegador:

Visitante  →  site da agência  →  servidor do site  →  API da Avoei
              (navegador)          (guarda o token)

Assim o token fica só no servidor. Isso também permite guardar as respostas (veja a seção seguinte) e reduz o número de chamadas à API, o que deixa o site mais rápido.

  • Nunca coloque o token em JavaScript público, no HTML, no localStorage, no pacote (bundle) do front-end, em aplicativos móveis distribuídos ao público ou em repositórios de código.
  • Guarde o token em variáveis de ambiente ou em um gerenciador de segredos.
  • Use um token por sistema e revogue os que não são mais usados. Veja Tokens de API.
  • Se suspeitar que um token vazou, revogue-o imediatamente e gere outro.

Guarde as respostas em cache​

Os dados da agência mudam pouco: as viagens, os depoimentos, a empresa e o SEO só mudam quando alguém da agência os edita. Consultar a API a cada visita ao seu site é desnecessário e consome o limite de requisições.

No servidor do seu site, guarde as respostas por até 30 minutos e atualize depois disso. Esse é o tempo seguro por causa das imagens: cada link de imagem vale por pelo menos 60 minutos a partir do momento em que a resposta é gerada. Guardar a resposta por mais de 60 minutos faz o seu site exibir links já vencidos.

Os cabeçalhos HTTP de toda resposta bem-sucedida ajudam a economizar dados:

  • Cache-Control: private, max-age=60: a resposta pode ser reutilizada por 60 segundos por quem a recebeu, mas nunca deve ser guardada em caches compartilhados (como um CDN ou proxy), porque pertence ao seu token.
  • ETag: uma identificação do conteúdo. Envie-a de volta no cabeçalho If-None-Match na próxima consulta: se nada mudou, a API responde 304 Not Modified, sem o conteúdo, e você continua usando a cópia que já tem.

Respostas de erro (401, 404, 422, 429, 500) não devem ser guardadas.

Os campos que apontam para imagens hospedadas pela Avoei — featured_image e media[].original_url (viagens), logo_url e favicon_url (empresa), image_url (depoimentos), og_image_url e twitter_image_url (SEO) — são links temporários e assinados.

  • Validade: cada link vale por pelo menos 60 minutos a partir do momento da resposta que o trouxe.
  • Os links mudam: a API renova os links a cada 30 minutos. Duas respostas em horários diferentes trazem endereços diferentes para a mesma imagem. Por isso, não use o link como identificador da imagem: use o id da viagem, ou o nome do arquivo quando houver.
  • Não salve os links no seu banco de dados nem os coloque em páginas que ficam armazenadas por muito tempo.
  • Se a sua página é gerada ou guardada em cache, renove os links junto com o resto dos dados, dentro do prazo de 30 minutos, ou baixe a imagem e sirva uma cópia sua.
  • O navegador pode guardar a imagem normalmente enquanto o link é o mesmo: dentro de uma janela de 30 minutos, o link de uma imagem não muda.

Trate os preços como texto​

Os preços chegam como texto com duas casas decimais, como "1290.00". Isso evita os erros de arredondamento dos números decimais.

  • Para exibir, formate o texto para reais, sem passar por cálculos.
  • Para calcular, use um tipo de número decimal apropriado, como Decimal no Python ou bcmath no PHP. Evite float.

Leia as datas do jeito certo​

Use starts_on e ends_on para exibir as datas de uma viagem, e datetime como veio para o horário das atividades. Converter esses valores como se fossem instantes em UTC faz o dia mudar. Veja Datas e horários.

Trate description como HTML​

O campo description de uma viagem é HTML, escrito no editor de texto da Avoei. Ao exibi-lo, use uma forma de renderização de HTML, e não texto puro. Se a página onde ele aparece for sensível, passe o conteúdo por um sanitizador de HTML antes de exibi-lo.

Não dependa de valores que podem mudar​

  • Use o id de uma viagem como chave no seu sistema. O slug (o endereço da viagem) pode ser alterado pela agência; quando isso acontece, atualize-o na sua cópia a cada sincronização.
  • Ignore campos desconhecidos. Recomendamos que a sua integração leia apenas os campos de que precisa e ignore o restante, para não quebrar se novos campos forem adicionados.
  • Não dependa do texto de message nem das mensagens de erro. Use o código HTTP e as chaves de errors.

Trate os erros​

  • Repita apenas 429 e 500, com pausa entre as tentativas. Veja Erros.
  • Defina um limite de tempo (timeout) para as requisições, para que uma resposta lenta não trave o seu sistema.
  • Registre o código de status e o endereço chamado quando algo falhar.

Consulte só o que precisa​

  • Use filtros e per_page para trazer menos dados.
  • Não chame a lista de viagens para encontrar uma só: se você já tem o slug, use Consultar uma viagem.