Usar bem a API: cache, webhooks e limites de taxa

Premium

Otimizar as chamadas à API do Omniscol: usar os ETags para evitar recuperar dados inalterados, manter as respostas em cache, receber notificações de alteração por meio de webhooks e respeitar os limites de taxa por endereço IP e por chave de API.

Uma integração que consulta o Omniscol a cada minuto para verificar se os dados mudaram recebe, na maioria das vezes, a mesma resposta da chamada anterior. Ela consome sua cota à toa e sobrecarrega o servidor sem obter nenhuma informação nova.

Esta página apresenta os mecanismos que permitem evitar essas chamadas desnecessárias e os limites de taxa aplicáveis à API.

Evitar recuperar dados inalterados

A maioria das respostas de leitura da API traz um cabeçalho ETag, que identifica uma versão da resposta. Guarde esse identificador junto com os dados recebidos e envie-o na chamada seguinte, no cabeçalho If-None-Match:

curl -i -G "https://sua-instituicao.omniscol.com/api/schedules/lessons/20261102-20261108" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'If-None-Match: W/"os1.…"'

Se os dados não mudaram, o Omniscol responde 304 Not Modified, sem corpo de resposta. Você pode então reutilizar os dados guardados em cache. Caso contrário, você recebe uma resposta 200 OK completa, acompanhada de um novo ETag.

O ETag é um valor opaco: guarde-o e reenvie-o exatamente como foi recebido, com as aspas e o prefixo W/, sem tentar construí-lo nem decodificá-lo. Ele é específico da requisição que o produziu e do acesso utilizado: não o reutilize para outra URL nem com outro token.

O cabeçalho Cache-Control: private, no-cache indica que a resposta pode ser guardada em um cache privado, mas que deve ser revalidada junto ao Omniscol antes de ser reutilizada. É exatamente a função do If-None-Match.

Algumas respostas não trazem ETag, principalmente quando dependem da data do dia e podem mudar sem que os dados da conta sejam alterados. Essas respostas devem ser recuperadas novamente a cada chamada.

Após a implantação de uma nova versão do Omniscol, os ETags são renovados, mesmo que os dados não tenham mudado. A primeira chamada recebe então uma resposta 200, e as chamadas seguintes voltam a se beneficiar das respostas 304.

O 304 também reduz o processamento no servidor. Na maioria dos casos, quando nenhum dado da conta mudou desde a última chamada, o Omniscol pode responder sem sequer reler os dados envolvidos, e esse 304 não é então contabilizado na cota associada à sua chave de API. Um 304 obtido após a releitura dos dados, por sua vez, é contabilizado como uma resposta comum.

A revalidação regular continua, portanto, barata quando os dados estão inalterados. Ela permanece, no entanto, sujeita ao limite geral por endereço IP.

Manter as respostas em cache

Se vários usuários ou várias telas do seu aplicativo consultam os mesmos dados, não é necessário consultar o Omniscol para cada um deles.

Guarde as respostas e seus ETags em um cache do aplicativo sob seu controle, por exemplo Redis, Memcached ou uma tabela de banco de dados. Seu aplicativo pode então servir os dados a partir desse cache, que se encarrega de revalidá-los junto ao Omniscol com If-None-Match, em intervalos regulares ou quando um webhook sinaliza uma alteração.

A chave de cache deve levar em conta a URL completa, o token de autenticação utilizado e, quando você os utiliza, o corpo da requisição GET e os cabeçalhos que fazem a resposta variar, como Accept-Language. Dois tokens com direitos diferentes podem dar acesso a dados diferentes: uma resposta obtida com um deles nunca deve ser servida a um usuário cujos direitos não permitam acessá-la.

Guarde também o corpo de cada resposta junto com seu ETag. Sem os dados correspondentes, uma resposta 304 não permite reconstituir o resultado esperado.

Esse cache do aplicativo é distinto de um cache HTTP compartilhado: a diretiva Cache-Control: private proíbe este último de armazenar as respostas.

Receber notificações em vez de consultar regularmente

Em vez de verificar periodicamente se os dados mudaram, você pode pedir ao Omniscol que notifique seu aplicativo quando ocorrer uma alteração.

Esse mecanismo se baseia nos webhooks, configuráveis na tela de personalização da API (veja Personalização de API). Um webhook pode monitorar um ponto de acesso específico ou um evento que reúne várias alterações, como a alteração de um horário.

Invalidar o cache ao receber um webhook

O uso mais simples consiste em tratar o webhook como um sinal de invalidação.

Quando uma notificação chega, seu aplicativo marca os dados envolvidos como desatualizados e os revalida junto ao Omniscol. Não é necessário interpretar o conteúdo da alteração: o webhook indica apenas que uma nova verificação é necessária.

Esse funcionamento se combina naturalmente com o cache descrito anteriormente.

Sincronizar as aulas por diferencial

Se você mantém uma cópia sincronizada das aulas, a opção Com dados do evento de alteração de horário permite receber um diferencial contendo as aulas adicionadas, modificadas e excluídas.

Seu aplicativo pode então aplicar somente essas mudanças, sem recuperar de novo a totalidade do horário.

Garantir o recebimento das notificações

O Omniscol faz uma única tentativa de envio por webhook. Ele espera no máximo quatro segundos, não tenta de novo em caso de falha e registra a falha em seus logs.

Seu servidor deve, portanto, confirmar o recebimento rapidamente, com uma resposta 200 OK ou 202 Accepted, e depois realizar o processamento necessário de forma assíncrona.

Mantenha também uma revalidação periódica como mecanismo de recuperação. Se seu servidor estava indisponível no momento do envio de um webhook, essa verificação permitirá detectar as alterações perdidas. Graças às respostas 304, ela continua barata quando os dados estão atualizados.

Proteger os webhooks

Para verificar que uma notificação vem realmente do Omniscol, configure um cabeçalho HTTP personalizado contendo um segredo conhecido somente pelo seu aplicativo e pelo Omniscol. Seu servidor deve recusar as chamadas que não apresentarem o valor esperado.

Dois cabeçalhos adicionais fornecem informações sobre o contexto da notificação:

  • X-School identifica a conta Omniscol envolvida;
  • X-OS-auth contém o token de autenticação do usuário que originou a alteração.

O token transmitido em X-OS-auth é confidencial. Não o registre em seus logs, não o transmita a outros serviços e restrinja rigorosamente o acesso a ele.

Pedir apenas os dados necessários

Uma resposta com menos dados costuma ser mais rápida de produzir, de transferir e de guardar em cache.

Para as aulas, limite o período solicitado e filtre os resultados pelas entidades que lhe interessam (veja API das aulas).

Para as buscas, o ponto de acesso search/query oferece filtros, projeção de campos e paginação (veja Consultas avançadas).

Para atualizar um grande número de itens da mesma natureza (turmas, salas, disciplinas etc.), prefira os pontos de acesso que permitem enviar uma coleção completa em uma única requisição, quando estiverem disponíveis na documentação OpenAPI, em vez de multiplicar as chamadas unitárias.

Respeitar os limites de taxa

Dois limites de taxa se aplicam às chamadas à API. Quando um limite é atingido, o Omniscol responde 429 Too Many Requests, acompanhado de um cabeçalho Retry-After que indica o número de segundos a esperar antes de repetir a requisição.

Limite por endereço IP

O limite geral é de 300 requisições por janela de 10 segundos, somando todos os pontos de acesso da API, incluindo MCP e os painéis de exibição.

Esse limite costuma ser suficiente para uma integração bem projetada. Ele pode ser atingido, porém, por loops de chamadas sem temporização ou por um número excessivo de requisições paralelas.

Limite por chave de API

Os tokens emitidos a partir de uma mesma chave de API compartilham duas cotas:

  • 60 requisições por minuto;
  • 5.000 requisições por dia.

As respostas podem trazer os cabeçalhos a seguir, que permitem acompanhar o consumo:

  • RateLimit-Policy indica as cotas aplicáveis, por exemplo 60;w=60, 5000;w=86400;
  • RateLimit-Limit indica a cota correspondente ao limite mais próximo de ser atingido;
  • RateLimit-Remaining indica o número de requisições ainda disponíveis para essa cota;
  • RateLimit-Reset indica o número de segundos até sua renovação.

Esses cabeçalhos estão ausentes, em especial, das respostas 304 obtidas sem releitura dos dados: a ausência deles não significa que a cota esteja esgotada.

Quando a cota se esgota, a resposta 429 indica também o tempo de espera em seu corpo, por meio do campo retry_after.

As respostas 304 obtidas sem releitura dos dados não são contabilizadas nessas cotas, mas continuam sujeitas ao limite geral por endereço IP.

Se esses limites atrapalham um uso legítimo da API, entre em contato conosco em vez de multiplicar as chaves.

Tratar erros e novas tentativas

Após uma resposta 429

Respeite o tempo indicado por Retry-After antes de repetir a requisição. Tentar de novo imediatamente é inútil e pode prolongar a situação, principalmente se vários processos do seu aplicativo fazem novas tentativas ao mesmo tempo.

Após um erro de servidor ou um tempo esgotado

Após um erro 5xx ou um estouro do tempo de espera, uma requisição de leitura pode ser repetida com um intervalo crescente entre as tentativas: um segundo, depois dois, depois quatro, por exemplo, até um número máximo de tentativas.

Para uma requisição de escrita, a situação é diferente: a alteração pode ter sido registrada mesmo que a resposta nunca tenha chegado até você. Verifique o estado real dos dados antes de repetir a operação, para evitar alterações duplicadas.

Após uma resposta 401

Uma resposta 401 Unauthorized geralmente não pode ser resolvida por uma nova tentativa com o mesmo token. Ela pode indicar, em especial, que o token expirou, que sua chave de API foi excluída ou expirou, ou que o ponto de acesso solicitado não faz parte dos que ela autoriza.

Verifique o token e as autorizações associadas antes de repetir a chamada (veja API Omniscol).

Ver também