Using the API well: caching, webhooks and rate limits

Premium

Optimize your calls to the Omniscol API: use ETags to avoid fetching unchanged data, keep responses in a cache, get notified of changes through webhooks and stay within the rate limits per IP address and per API key.

An integration that polls Omniscol every minute to check whether data has changed gets, most of the time, the same response as on its previous call. It uses up its quota for nothing and loads the server without obtaining any new information.

This page describes the mechanisms that let you avoid these unnecessary calls and the rate limits that apply to the API.

Skipping unchanged data

Most read responses of the API include an ETag header, which identifies a version of the response. Keep this identifier with the data you received and send it on the next call in the If-None-Match header:

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

If the data has not changed, Omniscol answers 304 Not Modified with no response body. You can then reuse the data you have cached. Otherwise you receive a full 200 OK response, along with a new ETag.

The ETag is an opaque value: store it and send it back unchanged, quotes and W/ prefix included, without trying to build or decode it. It is specific to the request that produced it and to the access used: do not reuse it for another URL or with another token.

The Cache-Control: private, no-cache header states that the response may be stored in a private cache, but that it must be revalidated with Omniscol before being reused. This is exactly what If-None-Match is for.

Some responses carry no ETag, notably when they depend on today's date and can change without any change to the account's data. These responses must be fetched again on every call.

After a new version of Omniscol is deployed, ETags are renewed, even if the data has not changed. The first call then receives a 200 response, and the following calls can benefit from 304 responses again.

A 304 also reduces the work done on the server. In most cases, when no data of the account has changed since your last call, Omniscol can answer without even rereading the data concerned, and that 304 is then not counted against the quota of your API key. A 304 obtained after rereading the data is counted like any ordinary response.

Regular revalidation therefore remains inexpensive when the data is unchanged. It is nevertheless still subject to the general limit per IP address.

Keeping responses in a cache

If several users or several screens of your application consult the same data, there is no need to query Omniscol for each of them.

Keep the responses and their ETags in an application cache under your control, for example Redis, Memcached or a database table. Your application can then serve the data from this cache, which takes care of revalidating it with Omniscol using If-None-Match, at regular intervals or when a webhook signals a change.

The cache key must take into account the full URL, the authentication token used and, when you use them, the body of the GET request and the headers that make the response vary, such as Accept-Language. Two tokens with different rights may give access to different data: a response obtained with one must never be served to a user whose rights do not allow them to see it.

Also keep the body of each response with its ETag. Without the corresponding data, a 304 response does not let you rebuild the expected result.

This application cache is distinct from a shared HTTP cache: the Cache-Control: private directive forbids the latter from storing the responses.

Receiving notifications instead of polling

Instead of periodically checking whether data has changed, you can ask Omniscol to notify your application when a change occurs.

This mechanism relies on webhooks, which you configure on the API customization screen (see API tweaks). A webhook can watch a specific endpoint or an event grouping several changes, such as a timetable change.

Invalidating the cache when a webhook is received

The simplest use is to treat the webhook as an invalidation signal.

When a notification arrives, your application marks the data concerned as stale and revalidates it with Omniscol. There is no need to interpret the content of the change: the webhook simply indicates that a new check is needed.

This combines naturally with the cache described above.

Synchronizing lessons with a diff

If you maintain a synchronized copy of the lessons, the With data option of the timetable change event lets you receive a diff containing the lessons that were added, modified and deleted.

Your application can then apply only those changes, without fetching the whole timetable again.

Making sure notifications are received

Omniscol makes only one delivery attempt per webhook. It waits four seconds at most, does not retry on failure and records the failure in its logs.

Your server must therefore acknowledge receipt quickly, with a 200 OK or 202 Accepted response, and then do the necessary processing asynchronously.

Also keep a periodic revalidation as a catch-up mechanism. If your server was unavailable when a webhook was sent, this check will detect the changes you missed. Thanks to 304 responses, it remains inexpensive when the data is up to date.

Securing webhooks

To verify that a notification really comes from Omniscol, configure a custom HTTP header containing a secret known only to your application and to Omniscol. Your server must reject calls that do not present the expected value.

Two additional headers provide information about the context of the notification:

  • X-School identifies the Omniscol account concerned;
  • X-OS-auth contains the authentication token of the user who made the change.

The token sent in X-OS-auth is confidential. Do not write it to your logs, do not pass it on to other services and restrict access to it strictly.

Requesting only the data you need

A response containing less data is generally faster to produce, to transfer and to cache.

For lessons, limit the period requested and filter the results on the entities you are interested in (see Lessons API).

For searches, the search/query endpoint offers filters, field projection and pagination (see Advanced queries).

To update a large number of items of the same kind (classes, classrooms, subjects, etc.), prefer the endpoints that accept a whole collection in a single request, when they are available in the OpenAPI documentation, rather than multiplying individual calls.

Respecting rate limits

Two rate limits apply to API calls. When a limit is reached, Omniscol answers 429 Too Many Requests, with a Retry-After header giving the number of seconds to wait before repeating the request.

Limit per IP address

The general limit is 300 requests per 10-second window, across all API endpoints, including MCP and display panels.

This threshold is generally sufficient for a well-designed integration. It can nevertheless be reached by loops of calls with no delay or by an excessive number of parallel requests.

Limit per API key

Tokens issued from the same API key share two quotas:

  • 60 requests per minute;
  • 5,000 requests per day.

Responses may carry the following headers, which let you track consumption:

  • RateLimit-Policy gives the quotas that apply, for example 60;w=60, 5000;w=86400;
  • RateLimit-Limit gives the quota corresponding to the limit closest to being reached;
  • RateLimit-Remaining gives the number of requests still available for that quota;
  • RateLimit-Reset gives the number of seconds before it is renewed.

These headers are notably absent from 304 responses obtained without rereading the data: their absence does not mean the quota is used up.

When the quota is used up, the 429 response also gives the waiting time in its body, in the retry_after field.

304 responses obtained without rereading the data are not counted against these quotas, but remain subject to the general limit per IP address.

If these limits get in the way of a legitimate use of the API, contact us rather than multiplying keys.

Handling errors and retries

After a 429 response

Respect the delay given by Retry-After before repeating the request. Retrying immediately is pointless and can prolong the situation, especially if several processes of your application retry at the same time.

After a server error or a timeout

After a 5xx error or a timeout, a read request can be repeated with an increasing delay between attempts: one second, then two, then four, for example, up to a maximum number of tries.

For a write request, the situation is different: the change may have been saved even though the response never reached you. Check the actual state of the data before repeating the operation, to avoid duplicate changes.

After a 401 response

A 401 Unauthorized response generally cannot be resolved by retrying with the same token. It may indicate in particular that the token has expired, that its API key has been deleted or has expired, or that the requested endpoint is not one of those it allows.

Check the token and its associated permissions before repeating the call (see Omniscol API).

See also