API-Warmer

Halte REST- und GraphQL-Endpunkte warm — mit echten Methoden, Headern, Cookies, Bodies und Konfigurationsmatrizen.

13 min read

APIs werden genauso kalt wie Webseiten. Wenn die Erstellung einer JSON-Antwort teuer ist und in deinem CDN oder Gateway zwischengespeichert wird, zahlt der erste Client nach Ablauf die gleiche Strafe wie ein Website-Besucher.

API warmers löst das. Du wirst separat von der Website warmers unter Konto → API Warmers verwaltet und haben ihre eigenen Planlimits.

Getrennt von der Website warmers

API warmers sind eine eigenständige Funktion mit eigener Berechtigung. Wenn der Abschnitt fehlt oder gesperrt ist, sind sie in deinem Plan nicht enthalten – siehe Pläne und Einschränkungen.

Wann sollte man eines verwenden?

Situation	Warum eine API warmer hilft
Eine kopflose Storefront oder Website	Produkt-, Inventar- und Inhalts-JSON werden bei jedem Seitenrendering abgerufen. Durch die Erwärmung dieser Strecken bleibt die gesamte Frontpartie schnell.
Eine öffentliche Entwickler-API	Beliebte Endpunkte und Dokumentationsbeispiele bleiben reaktionsfähig und sind für denjenigen, der zuerst anruft, nicht langsam.
Eine Backend-für-Frontend-Ebene	Der Neuaufbau aggregierter Endpunkte, die sich auf mehrere Dienste verteilen, ist kostspielig. deine Erwärmung schützt Mobil- und Web-Clients.
Schwere GraphQL Operationen	Normalerweise dominieren eine Handvoll Suchanfragen den Traffic. Das Erwärmen dieser spezifischen Vorgänge ist weitaus wichtiger, als nur einmal `/graphql` zu drücken.

Eine API warmer ist nicht nützlich für Endpunkte, die nie zwischengespeichert werden oder die pro Benutzer eindeutig sind und daher keine gemeinsam genutzte zwischengespeicherte Kopie zum Füllen haben.

Erstellen einer API warmer

1
Überprüfen du die API hostname
Endpunkt-URLs müssen ein verifiziertes hostname verwenden, genau wie Website warmers. Siehe Hostname Verifizierung.
2
Benennen du die warmer und lassen du sie inaktiv
Zuerst konfigurieren, aktivieren, wenn du zufrieden sind.
3
Fügen du einen oder mehrere Endpunkte hinzu
Jeder Endpunkt verfügt über eine URL und eine HTTP-Methode sowie optional eine Bezeichnung, einen Text und einen Inhaltstyp.
4
Fügen du die Authentifizierung hinzu, wenn der Endpunkt sie benötigt
Globale Header und Cookies werden auf jede Anfrage des warmer angewendet.
5
Optional mit einer Konfigurationsmatrix erweitern
Decken du viele Varianten ab – Gebietsschemas, Mandanten, IDs –, ohne Dutzende nahezu identischer warmers zu erstellen.
6
Legen du die Rate und die Intervalle fest und aktivieren du sie dann
Dieselbe Idee wie auf der Website warmers: Erwärmen du es oft genug, um die TTL deines Caches zu übertreffen, und langsam genug, um nicht zu schmerzen.

Endpunkte

Jeder Endpunkt im warmer wird unabhängig konfiguriert:

Etikett: Ein optionaler, für Menschen lesbarer Name, damit eine lange Liste von Endpunkten lesbar bleibt.
URL: Die vollständige Endpunktadresse auf einem verifizierten hostname. Kann Pfadplatzhalter wie {id} oder :id enthalten, wenn es mit einer PATH-Dimension gepaart wird.
Methode: GET, POST und andere, abhängig von deinem Plan. Pläne erlauben in der Regel standardmäßig GET und HEAD, mit mehr Methoden auf höheren Ebenen.
Protokoll: REST oder GRAPHQL. Wenn du GraphQL wählen, werden die Operations- und Abfragefelder angezeigt.
Body-Vorlage anfordern: Der zu sendende Körper für Methoden, die einen tragen. Erfordert die Berechtigung für den API-Anfragetext.
Inhaltstyp: Der Inhaltstyp des Anforderungstexts, normalerweise application/json.
Purge → Rewarm: Markiert den Endpunkt als sicher für zwei Aufrufe und ermöglicht so den Kalt-/Warm-Doppelabruf, der die Verbesserung misst. Aktivieren du es nur, wenn ein zweimaliger Anruf wirklich keine Nebenwirkungen hat.
Aktiviert: Ob dieser spezifische Endpunkt in Läufen enthalten ist. Praktisch, um einen Endpunkt vorübergehend zu deaktivieren, ohne ihn zu löschen.

Seien du vorsichtig, wenn du Schreibvorgänge als idempotent kennzeichnen

Ein doppelter Abruf auf einem Endpunkt, der Bestellungen erstellt, E-Mails sendet oder Karten belastet, führt dies zweimal aus. Markieren du einen Endpunkt nur dann als idempotent, wenn seine Wiederholung wirklich harmlos ist.

Konfigurationsmatrizen

Die meisten APIs haben Varianten: Derselbe Endpunkt wird pro Gebietsschema, pro Mandant, pro Währung oder pro ID aufgerufen. Es ist nicht möglich, für jeden eine warmer zu erstellen.

Eine Konfigurationsmatrix löst dieses Problem. du definieren Dimensionen mit mehreren Werten und Cache Rocket erweitert das vollständige kartesische Produkt in einzelne warme Anfragen.

Dimensionsart	Fügt Werte ein	Beispiel
`QUERY`	Die Abfragezeichenfolge	`locale=en`, `locale=nl`, `locale=de`
`HEADER`	Ein Anforderungsheader	`X-Tenant: acme`, `X-Tenant: globex`
`COOKIE`	Ein Keks	`currency=EUR`, `currency=USD`
`PATH`	Ein `{placeholder}` in der URL	`{id}` → `1`, `2`, `3`

Ein gelungenes Beispiel

text

Endpoint:  GET https://api.example.com/v1/products/{category}

Dimensions:
  PATH   category = shoes, bags, hats
  QUERY  locale   = en, nl

Expands to 6 warm requests:
  /v1/products/shoes?locale=en
  /v1/products/shoes?locale=nl
  /v1/products/bags?locale=en
  /v1/products/bags?locale=nl
  /v1/products/hats?locale=en
  /v1/products/hats?locale=nl

Kombinationen vervielfachen sich schnell

Die Gesamtanzahl der Anfragen ist das Produkt der Werteanzahl jeder Dimension. Drei Dimensionen mit jeweils fünf Werten ergeben 125 Kombinationen von einem einzelnen Endpunkt. Das Formular zeigt eine laufende Zählung und das Maximum deines Plans – beobachten du es, während du Werte hinzufügen.

Wenn du das Planmaximum überschreiten, wird warmer nicht gespeichert. Werte reduzieren, auf mehrere warmers aufteilen oder hochrüsten.

Authentifizierung

Globale Anforderungsheader und Cookies werden auf jede Variante angewendet, die warmer generiert. Hier wird ein Authorization-Header oder ein Sitzungscookie abgelegt.

Typische Authentifizierungsheader

text

Authorization: Bearer YOUR_LONG_LIVED_TOKEN
X-Api-Key: YOUR_API_KEY

Erwärmen du die Variante, die echte Kunden tatsächlich wünschen

Wenn dein Cache um Authorization schwankt, füllt das Aufwärmen mit einem Service-Token einen mit diesem Token verschlüsselten Cache-Eintrag – den kein echter Client jemals erreichen wird. Für gemeinsame, zwischenspeicherbare Antworten erwärmen du sich auf die gleiche Weise, wie ein gewöhnlicher Client den Endpunkt aufruft.

Token verfallen. Wenn eine API warmer plötzlich anfängt, 401 zurückzugeben, muss zunächst ein hartcodiertes Token überprüft werden.

GraphQL

GraphQL benötigt eine eigene Behandlung, da die Leistung von der spezifischen Operation und nicht vom Endpunktpfad abhängt. Wenn du einmal /graphql drücken, erfahren du nichts; Wenn du deine drei schwersten Fragen aufwärmen, erfahren du alles.

Setzen du das Protokoll eines Endpunkts auf GraphQL und geben du dann Folgendes ein:

GraphQL-Operation – unabhängig davon, ob es sich um eine query oder eine mutation handelt. Erwärmungsmutationen sind fast nie angebracht.
GraphQL Abfrage – das zu sendende Vorgangsdokument.
Variablen – stellen du sie über die Anfragetextvorlage oder als Matrixdimensionswerte bereit, um mehrere Variablensätze aufzuwärmen.

Note

GraphQL Die Erwärmung wird durch einen eigenen Plananspruch zusätzlich zu API warmers begrenzt.

OpenAPI-Import

Bei unterstützten Plänen können du Endpunkte direkt aus einer OpenAPI 3-Spezifikation importieren, anstatt sie einzugeben. Fügen du die URL einer JSON- oder YAML-Spezifikation ein und klicken du auf Importieren; Erkannte Endpunkte werden zu warmer hinzugefügt und können bereinigt und angepasst werden.

Tip

Der Import bringt alles ein, was in der Spezifikation beschrieben wird, einschließlich Schreibvorgängen. Sehen du sich die Liste sorgfältig an und deaktivieren du vor der Aktivierung alles, was nicht nach einem Zeitplan aufgerufen werden soll.

Grenzen und Terminplanung

Maximale Erwärmung pro Minute: Ratenobergrenze für diese API warmer, entspricht den maximalen URLs pro Minute auf einer Website warmer.
Timeout anfordern: Wie lange muss man auf eine Antwort warten, bevor man aufgibt?
Autostartintervall: Wie oft ein neuer Warmdurchgang beginnt, in Sekunden.
Enqueue-Intervall: Tempo der erneut in die Warteschlange gestellten Arbeit innerhalb des Zyklus.
Auf HTTPS umschreiben: Aktualisieren du http:// Endpunkt-URLs auf https://.
Warmer Zeitplan: Fenster zu Haupt- und Nebenzeiten, dasselbe JSON-Format wie auf der Website warmers. Siehe Erweiterte Erwärmung.

dein Plan begrenzt außerdem die Anzahl der APIs auf warmers, der Endpunkte auf warmer und der Kombinationen auf warmer.

Häufige Probleme

Alles gibt 401 oder 403 zurück.: Der Authentifizierungsheader oder das Cookie fehlt, ist falsch oder abgelaufen. Üblicherweise sind langlebige Token die Ursache – prüfen du, ob der Token noch gültig ist und nicht rotiert wurde.
Die warmer wird nicht gespeichert, da zu viele Kombinationen zitiert werden.: deine Matrix erweitert sich über das Planmaximum hinaus. Reduzieren du Dimensionswerte, teilen du Endpunkte auf mehrere warmers auf oder führen du ein Upgrade durch.
Die Methode, die ich benötige, ist nicht im Dropdown-Menü.: Pläne beschränken, welche HTTP-Methoden zulässig sind. Niedrigere Ebenen erlauben normalerweise nur GET und HEAD.
Die Erwärmung läuft sauber, aber die Reaktionen für echte Kunden sind immer noch langsam.: du füllen wahrscheinlich eine andere Cache-Variante als vom Client angefordert – häufig aufgrund eines Authorization-Headers, eines Cookies oder eines Headers, von dem dein CDN abhängt. Vergleichen du die genaue Anfrage, die ein echter Kunde sendet, mit der, die der warmer sendet.
Kann ich einen Endpunkt erwärmen, der ein signiertes, kurzlebiges Token erfordert?: Nicht zuverlässig, da der warmer nicht pro Lauf eine neue Signatur generieren kann. Stellen du entweder eine zwischenspeicherbare, nicht authentifizierte Variante bereit oder verwenden du ein langlebiges Service-Token, wenn dies sicher ist.