Idempotenz
Bricht die Verbindung nach einem POST ab, weißt du nicht, ob der Aufruf angekommen ist. Mit einem Idempotency-Key wiederholst du ihn, ohne dass die Aktion doppelt läuft.
Der Header
Idempotency-Keyist optional und für jeden POST-Aufruf empfohlen. Ohne den Header gibt es keine Idempotenz: Ein wiederholter Aufruf läuft dann ein zweites Mal.- Der Wert besteht aus 1 bis 128 sichtbaren ASCII-Zeichen. Ein leerer oder ungültiger Wert ergibt 400
VALIDATION_ERROR. Eine zufällige UUID eignet sich gut. - Ein Key ist 24 Stunden gültig, getrennt für jedes Token.
- Erzeuge den Key einmal je Aktion und schicke bei jeder Wiederholung denselben.
cURL: Neustart mit Idempotency-Key
curl -X POST "https://api.zenit-hosting.de/api/developer/v1/servers/$SERVER_ID/power" \
-H "Authorization: Bearer $ZENIT_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"signal": "restart"}'JavaScript: Neustart mit Idempotency-Key
const BASE = 'https://api.zenit-hosting.de/api/developer/v1';
// Jede neue Aktion bekommt einen neuen Key. Nur beim Wiederholen derselben Aktion reichst du ihn weiter.
async function restart(serverId, key = crypto.randomUUID()) {
return fetch(BASE + '/servers/' + serverId + '/power', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.ZENIT_TOKEN,
'Idempotency-Key': key,
'Content-Type': 'application/json',
},
body: JSON.stringify({ signal: 'restart' }),
});
}
async function restartWithRetry(serverId) {
const key = crypto.randomUUID(); // ein Key je Aktion
for (let attempt = 0; attempt < 3; attempt++) {
try {
return await restart(serverId, key); // bei jedem Versuch derselbe Key
} catch {
// Verbindungsfehler: Du weißt nicht, ob der Aufruf angekommen ist. Mit demselben Key ist die Wiederholung sicher.
}
}
throw new Error('Neustart nicht bestätigt');
}Was bei einer Wiederholung passiert
| Lage | Antwort |
|---|---|
| Gleicher Key, gleicher Aufruf | Die API liefert die gespeicherte Antwort noch einmal, mit dem Header Idempotency-Replayed: true. Die Aktion läuft nicht ein zweites Mal. |
| Gleicher Key, der erste Aufruf läuft noch | 409 IDEMPOTENCY_IN_PROGRESS. Warte kurz und sende denselben Aufruf mit demselben Key erneut. |
| Gleicher Key, anderer Aufruf | 422 IDEMPOTENCY_KEY_REUSED. Erzeuge für jede neue Aktion einen neuen Key. |
Beispiel einer wiederholten Antwort
HTTP/1.1 202 Accepted
Idempotency-Replayed: true
{ "signal": "restart", "jobId": "b1f3c6d2-7a49-4e08-9c15-3d8e2a6f0b47", "deduped": false }Welche Antworten gespeichert werden
Die API speichert Antworten mit einem Status unter 500. Ausgenommen sind 409 IDEMPOTENCY_IN_PROGRESS und 429. Ein Aufruf, der mit 429 oder einem Serverfehler endete, läuft deshalb bei einer Wiederholung mit demselben Key erneut. Wie du bei 429 wartest, steht unter Rate-Limits.
Nach einer Antwort unter 500 (außer 409 IDEMPOTENCY_IN_PROGRESS und 429) braucht ein neuer Versuch einen neuen Key. Mit dem alten Key bekämst du nur dieselbe gespeicherte Antwort noch einmal, etwa bei CAPACITY_UNAVAILABLE oder SERVER_NOT_READY.