Kosten en limieten

Bij een REST-API tel je verzoeken: elk verzoek is even duur. Dat klopt hier niet meer: themes(first: 250) met alle beelden erbij en theme { title } zijn niet hetzelfde. Daarom rekenen we punten.

Wat iets kost

De prijs wordt vooraf uit je query berekend, vóór er iets wordt uitgevoerd.

Name
Een scalar of enum
Type
0 punten
Description
id, title, status, createdAt zijn gratis. Vraag ze gerust allemaal op.
Name
Een object
Type
1 punt
Description
Elk veld dat een object teruggeeft: card, deceased, theme.
Name
Een connectie
Type
2 + first × de prijs per node
Description
Wat je maximaal vraagt bepaalt de prijs, niet wat je krijgt.
Name
Een mutatie
Type
10 + de prijs van de payload
Description
Schrijven is duurder dan lezen.

Drie queries, drie prijzen

# card = 1 object. De rest is gratis.
{
  card(id: "gid://rouwkaart/Card/069a…") {
    id
    status
    cardUrl
    createdAt
  }
}

Wat je terugkrijgt

Elk antwoord draagt extensions.cost, ook een antwoord met fouten.

Name
requestedQueryCost
Type
Int
Description
Wat de query maximaal kon kosten. Dit is wat er vooraf van je emmer af gaat.
Name
actualQueryCost
Type
Int
Description
Wat het werkelijk kostte, geteld aan wat er terugkwam. Het verschil gaat terug in je emmer. null als de query niet is uitgevoerd.
Name
throttleStatus.currentlyAvailable
Type
Int
Description
Hoeveel punten je nu hebt.
Name
throttleStatus.maximumAvailable
Type
Int
Description
Name
throttleStatus.restoreRate
Type
Int
Description
50 per seconde.

themes(first: 10), er kwam er één terug

{
  "data": { "themes": { "nodes": [{ "title": "Bloemen" }] } },
  "extensions": {
    "cost": {
      "requestedQueryCost": 12,
      "actualQueryCost": 3,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 997,
        "restoreRate": 50
      }
    }
  }
}

Je betaalt uiteindelijk voor wat je krijgt, niet voor wat je vraagt. Een connectie die om 250 regels vroeg en er 3 opleverde kost er 3; het verschil wordt teruggegeven zodra het antwoord klaar is.

Als het niet past

Past een query niet in je punten, dan wordt hij niet uitgevoerd. Je krijgt THROTTLED, een Retry-After-header met het aantal seconden, en je emmer blijft onaangeroerd.

Let op: één gulzige query kan in z'n eentje boven de 1000 uitkomen. Dan helpt wachten niet. Dan moet de query kleiner.

1002 punten: past nooit

# 2 + 250 × (edge + node + images + videos) = 1002
{
  themes(first: 250) {
    edges {
      node {
        images { url }
        videos { url }
      }
    }
  }
}

Het antwoord

{
  "errors": [
    {
      "message": "Throttled: deze query kost 1002 punten en er zijn er 1000 beschikbaar.",
      "extensions": { "code": "THROTTLED" }
    }
  ],
  "extensions": {
    "cost": {
      "requestedQueryCost": 1002,
      "actualQueryCost": null,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 1000,
        "restoreRate": 50
      }
    }
  }
}

Hoe je hier nooit last van hebt

In normaal gebruik kom je hier niet in de buurt: een kaart aanmaken kost 11 punten, een status opvragen 1. Je zou er ruim negentig per seconde kunnen doen. Drie gewoontes houden het zo:

Name
Vraag alleen wat je toont
Type
scheelt het meest
Description
Elk object dat je niet opvraagt kost niets én wordt niet opgehaald. Laat je theme weg uit een kaartquery, dan doen wij ook geen verzoek aan onze productcatalogus.
Name
Zet first op wat je nodig hebt
Description
first: 250 kost 250 keer de prijs per node, ook als er drie thema's zijn.
Name
Gebruik webhooks in plaats van pollen
Description
Een kaart elke minuut opvragen om te zien of er iets veranderd is, is precies wat webhooks overbodig maken.

Een limiet per pagina

first en last moeten tussen 1 en 250 liggen. Daarbuiten krijg je MAX_COST_EXCEEDED, geen stilzwijgend bijgeknipte lijst, want dan zou je denken dat je alles had.