Aanvragen, paginering en limieten

JSON-enveloppen

Antwoorden met één resource gebruiken bij succes de volgende indeling:

{ "data": {}, "request_id": "req_example" }

Lijsten bevatten ook pagineringsvelden:

{
  "data": [],
  "has_more": true,
  "next_cursor": "opaque-cursor",
  "request_id": "req_example"
}

Onbekende eigenschappen in een JSON-body worden geweigerd met unknown_field. Zo wordt een typefout bij een schrijfactie opgemerkt in plaats van stilzwijgend genegeerd.

Queryparameters werken anders: onbekende parameters worden genegeerd, niet geweigerd. Analysetools en proxy’s voegen regelmatig eigen parameters toe (utm_*, cf_*). Het zou onwenselijk zijn om een verder geldige aanvraag daarom te laten mislukken.

Standaardwaarden

De standaardwaarden zijn ingesteld op veilig interactief gebruik. Zo bestrijkt het gebruik standaard de laatste 30 dagen en tonen vertalingen standaard de 25 meest recente, niet-gearchiveerde records. Een aangevraagde lijstlimiet boven 100 wordt begrensd op 100.

Datums en tijdstempels gebruiken ISO 8601. JSON-veldnamen zijn snake_case. Velden die nog niet van toepassing zijn, zijn doorgaans null, zodat de resource-indeling tijdens de hele levenscyclus van een vertaling gelijk blijft.

Cursorpaginering

Geef next_cursor uit een antwoord ongewijzigd door in de volgende aanvraag. Stop wanneer de waarde null is of has_more de waarde false heeft.

let cursor;
do {
  const url = new URL('https://api.ai-glot.com/v1/batches');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const page = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.AIGLOT_API_KEY}` },
  }).then(response => response.json());

  for (const translation of page.data) console.log(translation.id);
  cursor = page.next_cursor;
} while (cursor);

Maak cursors niet zelf en pas ze niet aan. Cursorpaginering voorkomt dat een nieuw aangemaakte vertaling de rijen tussen pagina’s verschuift.

Snelheidslimieten

Per inloggegeven geldt een doorlopende limiet van 240 aanvragen per minuut en een pieklimiet van 40 aanvragen per 10 seconden. Een 429-antwoord bevat Retry-After; wacht de aangegeven tijd af voordat je het opnieuw probeert.

Elk antwoord bevat een header RateLimit-Policy met beide tijdvensters:

RateLimit-Policy: 240;w=60, 40;w=10

De header geeft alleen de limieten aan. Het resterende aantal aanvragen wordt niet gepubliceerd. Houd je daarom aan de gedocumenteerde limieten en beschouw 429 plus Retry-After als het signaal om gas terug te nemen.

Aanvraag-ID’s en nieuwe pogingen

Elk antwoord bevat een aanvraag-ID, zowel in de payload (request_id) als in de header X-Request-Id. Vermeld deze ID wanneer je contact opneemt met support.

Probeer het bij 429, 500, 502, 503 en 504 opnieuw met exponentiële back-off en jitter. Probeer validatie-, authenticatie-, rechten- en niet-gevonden-fouten niet opnieuw zonder de aanvraag aan te passen.

Afsluitende schuine strepen zijn toegestaan. De REST API verleent opzettelijk geen CORS-toestemming aan browsers, omdat inloggegevens van werkruimten thuishoren in vertrouwde code aan de serverzijde.