Idempotentie

Netwerken vallen halverwege weg. Als een aanroep een time-out geeft, weet je niet of Picked hem heeft ontvangen. Deze pagina legt uit welke aanroepen je veilig opnieuw kunt sturen.

Je eigen nummer is de sleutel

Orders en leveringen hebben al een nummer dat je eigen systeem ze geeft, en daaraan herkent Picked een herhaling. Het starten van een procesrun heeft zo'n nummer niet, dus dat neemt in plaats daarvan een Idempotency-Key-header:

Bij orders en ontvangsten geeft de eerste aanroep 201 Created, en elke herhaling 200 OK met een body van dezelfde vorm, zodat je koppeling beide als gelukt kan behandelen en het id kan bewaren dat ze terugkrijgt.

De Idempotency-Key-header

Stuur Idempotency-Key mee met een tekst van hooguit 255 tekens die uniek is voor het verzoek, zoals een UUID of je eigen opdrachtnummer. Picked bewaart het eerste antwoord 24 uur:

• Dezelfde sleutel opnieuw, voor hetzelfde verzoek: je krijgt het eerste antwoord terug, status en body, met de header Idempotency-Replayed: true. Er gebeurt niets opnieuw. De Location-header van het eerste antwoord komt niet terug; de _links erin wijzen naar dezelfde plek.
• Dezelfde sleutel voor een ander verzoek (een ander proces, of andere variabelen): 409 met de code conflict. Een sleutel wordt één keer per werkruimte gebruikt, naar welk endpoint hij ook ging.
• Een verzoek dat geweigerd werd (een 4xx of 5xx) bewaart geen sleutel, dus je kunt het verzoek aanpassen en opnieuw sturen met dezelfde sleutel.
• Twee verzoeken met dezelfde sleutel tegelijk: het tweede wacht op het eerste en krijgt dan zijn antwoord.

Sleutels worden exact vergeleken: abc en ABC zijn twee sleutels. Na 24 uur mag een sleutel opnieuw gebruikt worden.

Een herhaling verandert niets

Een herhaling geeft terug wat Picked al heeft, ongewijzigd. Staan er in de herhaling andere regels of een andere klant, dan worden die verschillen genegeerd: het is geen wijziging, en ook geen fout. Vergelijk het antwoord met wat je stuurde als je dat wilt weten.

Orders

Een external_id wordt per werkruimte één keer gebruikt, voorgoed. Importeer je hem opnieuw, dan krijg je die order terug, ook als die inmiddels is verzonden, geannuleerd of verwijderd.

Orders die binnenkomen via een gekoppelde webshop of marktplaats hebben hun eigen nummering, dus die tellen niet mee: een API-order en een winkelorder mogen hetzelfde nummer hebben. Orders die je team met de hand in Picked maakte of uit een spreadsheet importeerde, tellen wel mee.

Ontvangsten

Stuur altijd een reference mee. Zonder reference verzint Picked er zelf een, en meldt elke aanroep een nieuwe levering aan. Een nieuwe poging meldt dezelfde levering dan twee keer aan.

Komen twee aanroepen met dezelfde nieuwe reference op hetzelfde moment binnen, dan maakt de ene de ontvangst en geeft de andere 422 met een fout op reference. Stuur die tweede opnieuw: nu krijg je de ontvangst terug die de eerste maakte.

Procesgebeurtenissen

Een procesgebeurtenis is een signaal, geen record. Elke aanroep levert het opnieuw af, en maakt de processen wakker die er op dat moment op wachten. Stuur je hem twee keer, dan maakt de tweede keer meestal niets wakker, omdat de processen die de eerste aanroep wekte niet meer wachten.

Stuur een procesgebeurtenis in twee gevallen opnieuw: als de aanroep zelf mislukte, en als hij 200 gaf met id's onder deferred_task_batch_ids. Die processen pasten bij de gebeurtenis, maar konden nog niet verder, bij gebrek aan voorraad of capaciteit. Stuur de gebeurtenis later opnieuw, anders gaat het signaal voor hen verloren.

Controleren zonder te schrijven

Wil je weten of een order of ontvangst al bestaat, stuur de aanroep dan met de header Picked-Dry-Run: true. Het veld would in het antwoord zegt created of already_exists, en er wordt niets geschreven.