Idempotentie
Onze API ondersteunt idempotentie voor het veilig opnieuw proberen van requests zonder per ongeluk twee keer dezelfde bewerking uit te voeren. Gebruik bij het maken of bijwerken van een object (order, template) een idempotentie-key. Als er vervolgens een verbindingsfout optreedt, kun je het request veilig herhalen zonder het risico te lopen een tweede object (order, template) te maken of de update twee keer uit te voeren.
Met onze idempotentie functie kun je dus eenvoudig voorkomen dat een order twee keer naar hetzelfde adres of dezelfde persoon wordt verstuurd (binnen 24 uur). Ontdubbelen van je bestand is ook niet meer nodig als je idempotency keys gebruikt.
Concrete gebruiksvoorbeelden:
Gebruik het klant id om een idempotency key te genereren. Als ons systeem twee orders met dezelfde idempotency key ontvangt binnen 24 uur, wordt er maar 1 order uitgevoerd (de eerste).
Gebruik postcode en huisnummer om een idempotency key te genereren. Als ons systeem twee orders met dezelfde key ontvangt, wordt alleen de eerste order uitgevoerd.
Zo werkt het:
Om een idempotent request uit te voeren, geef je een extra Idempotency-Key: <key> header aan het request.
De idempotentie van Print.one werkt door de resulterende statuscode en hoofdtekst van het eerste request voor een bepaalde idempotentie-key op te slaan, ongeacht of deze is geslaagd of mislukt. Volgende requests met dezelfde sleutel retourneren hetzelfde resultaat, inclusief 500 fouten.
Een idempotentie-key is een unieke waarde die door de client wordt gegenereerd en die de server gebruikt om volgende nieuwe pogingen van hetzelfde request te herkennen. Hoe je unieke sleutels maakt, is aan jou, maar we raden aan om V4 UUID's te gebruiken, of een andere willekeurige tekenreeks met voldoende entropie om botsingen te voorkomen. Idempotentie-keys kunnen maximaal 255 tekens lang zijn.
Sleutels worden automatisch uit het systeem verwijderd nadat ze 24 uur oud zijn. De idempotentielaag vergelijkt binnenkomende parameters met die van het oorspronkelijke request en geeft een error als deze niet hetzelfde zijn. Dit betekent dat het niet mogelijk is om een request met een andere body te herhalen met dezelfde sleutel.
Alle POST- en PATCH-requests accepteren idempotentie sleutels. Het verzenden van idempotentie-keys in DELETE- en GET-requests heeft geen effect en moet worden vermeden, aangezien deze requests per definitie idempotent zijn.