Idempotenz
Alle Anlege-Anfragen (POST) benötigen den Header Idempotency-Key. Damit sind Wiederholungen sicher: Bricht eine Anfrage ab oder läuft in ein Timeout, senden Sie sie mit demselben Key erneut, ohne ein Duplikat zu erzeugen.
curl https://api-test.worklogx.com/api/v1/customers \
-X POST \
-H "Authorization: Bearer wlx_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-d '{"customerNumber": "K-10025", "name": "Muster Elektrotechnik GmbH"}'Ein erfolgreiches Anlegen liefert 201 Created mit der neuen Ressource.
#Regeln
| Situation | Ergebnis |
|---|---|
| Header fehlt oder ist leer | 400 idempotency_key_required |
| Key länger als 128 Zeichen | 400 validation_failed mit errors: [{"field": "Idempotency-Key", "code": "too_long"}] |
| Gleicher Key, gleicher Request-Body | Kein neuer Datensatz. 201 mit der Ressource aus der ersten Anfrage (im aktuellen Zustand). |
| Gleicher Key, anderer Request-Body | 409 idempotency_key_reused |
Keys gelten pro API Client und Endpunkt: Derselbe Key kann einmal für POST /v1/customers und einmal für POST /v1/projects verwendet werden.
#Empfehlungen
- Für jeden fachlichen Anlegevorgang einen neuen Zufallswert erzeugen, zum Beispiel eine UUID.
- Den Key zusammen mit dem offenen Vorgang speichern und bei jeder Wiederholung dieses Vorgangs wiederverwenden.
- Einen Key nie für einen anderen Datensatz wiederverwenden.
#PATCH-Anfragen
PATCH-Endpunkte verwenden keinen Idempotency-Key. Ein erneut gesendetes PATCH setzt dieselben Werte noch einmal.