Usar bem a API: cache, webhooks e limites de taxa
PremiumUma 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-Schoolidentifica a conta Omniscol envolvida;X-OS-authconté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-Policyindica as cotas aplicáveis, por exemplo60;w=60, 5000;w=86400;RateLimit-Limitindica a cota correspondente ao limite mais próximo de ser atingido;RateLimit-Remainingindica o número de requisições ainda disponíveis para essa cota;RateLimit-Resetindica 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).