Idempotency

Πώς να το χρησιμοποιήσετε

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key - μια τυχαία συμβολοσειρά έως 64 χαρακτήρες, μοναδική για κάθε λογική λειτουργία. Συνιστάται - ULID ή UUID v4.

Εγγυήσεις

• Κατά τη διάρκεια των 24 ωρών μετά το πρώτο αίτημα με αυτό το κλειδί, τα επαναλαμβανόμενα αιτήματα με το ίδιο κλειδί επιστρέφουν την ίδια απάντηση χωρίς επαναληπτικό υπολογισμό και χωρίς χρέωση πιστώσεων.
• Αν το σώμα του αιτήματος διαφέρει από το πρωτότυπο: επιστρέφεται 409 Conflict με κωδικό idempotency_key_reuse.
• Μετά από 24 ώρες το κλειδί ξεχαστεί, ένα νέο αίτημα με το ίδιο κλειδί θα είναι κανονικό.

Σημείωση

Idempotency - είναι προστασία από διπλή χρέωση σε περίπτωση αποτυχίας δικτύου, όχι cache. Για caching χρησιμοποίησε τον φυσικό μηχανισμό X-Cache (5 λεπτά, δες Πιστώσεις και όρια).

Πότε χρειάζεται

• Σε webhook handlers, όπου το retry έρχεται από εξωτερικό σύστημα (π.χ. payment provider ή CRM στέλνει ένα event που το parse και κάνεις υπολογισμό)
• Σε background jobs, όπου το retry είναι η τυπική συμπεριφορά σε περίπτωση σφαλμάτων
• Σε CI/CD pipelines, όπου ένα test μπορεί να ξανατρέξει

Για κανονικές αλληλεπιδράσεις “ο χρήστης πάτησε κουμπί → εμφανίστηκε χάρτης”, η ιδεμοποτικότητα δεν χρειάζεται - ο χρήστης θα δει το αποτέλεσμα και πάλι, συνήθως δεν υπάρχουν επαναλαμβανόμενα κλικ.

Πότε όχι να χρησιμοποιήσεις

• Μην βάζεις κλειδί για να εξοικονομήσεις πιστώσεις σε ίδια αιτήματα: για αυτό υπάρχει το X-Cache (δωρεάν, 5 λεπτά)
• Μην δημιουργείς κλειδί από hash(body): τότε θα χάσεις την προεπιλεγμένη συμπεριφορά του Idempotency-Key (επανάληψη 409 σε διαφορετικά body)