Idempotentsed päringud

Päring võib ebaõnnestuda ka siis, kui Sursa on töö juba ära teinud: ühendus katkeb või teie protsess taaskäivitub enne vastuse saabumist. Kui saadate sama päringu POST uuesti, võite luua teise kaardi või teise veebihaagi. Seda hoiab ära idempotentsusvõti: sama päringu kordamine ei käivita toimingut uuesti.

Saatke iga päringuga POST ja PATCH päis Idempotency-Key. Kui Sursa on selle võtmega päringut juba näinud, ei käivita see toimingut uuesti, vaid tagastab vastuse, mille salvestas esimesel korral.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

Korduv päring saab sama oleku ja keha mis esimene ning lisaks ühe päise:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

Korduval päringul on oma X-Request-Id.

Võtme valimine

Kasutage iga loogilise toimingu jaoks uut juhuslikku väärtust, näiteks UUID v4: „loo see kaart“, „registreeri see veebihaak“. Kasutage sama väärtust selle toimingu iga korduskatse puhul ja mitte kunagi mõne muu toimingu jaoks.
Hea võti tuletatakse teie enda andmetest, kui need on olemas, näiteks sync-2026-10-24-record-1042. Siis saadab sama võtme uuesti isegi taaskäivitatud töö, mis on oma mälu kaotanud.
Võti koosneb 1–255 prinditavast ASCII-märgist. Muu väärtus tagastab 400 koodiga api.idempotency_key_invalid.

Mida Sursa võtmega teeb

Olukord	Vastus
Esimene päring selle võtmega	Toiming käivitub tavapäraselt.
Sama võti, sama päring, esimene lõppes olekuga `2xx` või `4xx`	Salvestatud vastus päisega `Idempotency-Replayed: true`. Toimingut uuesti ei käivitata.
Sama võti, esimene päring on veel pooleli	`409` `api.idempotency_in_progress` päisega `Retry-After: 1`. Oodake ja proovige uuesti.
Sama võti, kuid erinev meetod, tee, `Content-Type` või keha	`409` `api.idempotency_mismatch`. Võti on juba teise päringuga seotud.
Esimene päring lõppes olekuga `5xx` või `429`	Võti vabastatakse: järgmine selle võtmega päring käivitab toimingu uuesti.

Võti kehtib 24 tundi. Pärast seda alustab sama võti uut toimingut.
Võtmed on iga organisatsiooni ja iga päringu tegija jaoks eraldi: kaks erinevat API-võtit võivad kasutada sama väärtust ilma teineteist mõjutamata.
Salvestatakse ka vastus olekuga 4xx. Päring, mis valideerimist ei läbinud, ebaõnnestub sama võtmega kordamisel samamoodi; parandage see ja saatke uue võtmega.

Millised päringud seda vajavad

Meetod	Idempotency-Key
`POST`, `PATCH`	Saatke see. Iga lõpp-punkt, mis salvestab oma vastuse kordamiseks, loetleb API teatmikus selle päise.
`GET`, `PUT`, `DELETE`	Ei ole vaja: neid meetodeid on oma olemuselt turvaline korrata. Päis võetakse vastu, kuid sellel ei ole mõju.
`POST`, mis ainult loeb, näiteks otsing, finantsaruanded ja `POST /v1/catalog/resolve`	Võetakse vastu, kuid midagi ei salvestata: päring lihtsalt käivitub uuesti.

Mõnda toimingut on turvaline korrata ka ilma päiseta:

PUT /v1/cards-by-external-id/{external_id} loob või asendab teie ID-ga kaardi; sama sisuga kordamine ei muuda midagi.
Kohandatud allika dokumente tuvastatakse teie välja external_id järgi; sama dokumendi uuesti saatmine tagastab unchanged.
Päringu POST /v1/chat voogedastatav vastus kasutab päise asemel keha välja request_id. Vt Küsimuste ja vastuste boti loomine.

Turvalised korduskatsed

Ühendage võti korduskatsete reeglitega juhendist Vead: looge võti üks kord enne esimest katset ja saatke see sama toimingu iga katsega.