Ārējais API maina versiju: kā sagatavot integrāciju bez darba pārtraukuma

API versijas maiņu sāciet ar izmantoto pieprasījumu un ienākošo notikumu uzskaiti. Pēc tam piegādātāja izmaiņas piesaistiet uzņēmuma darbībām: pasūtījuma izveidei, maksājuma atpazīšanai, rēķina statusam vai klienta datu atjaunošanai. Pirms pārslēgšanas katrai būtiskai darbībai vajadzīgs pārbaudāms sagaidāmais rezultāts un atbildīgais, kurš to pieņem. Nepārtraukta darbība ir migrācijas mērķis, ne garantija, ko dod jauns versijas numurs.

Vadītājam nav jāizlasa katra API dokumentācijas lappuse. Viņam jāspēj noskaidrot, kurš biznesa process var apstāties, kā kļūmi pamanīs un kas notiks ar pārejas laikā saņemtajiem datiem. Ar paziņojumu “izstrādātājs atjaunos bibliotēku” šiem jautājumiem vēl nav atbildēts.

API versijas maiņai vajadzīga faktiskā sākuma situācija

Pierakstiet pašreizējo API versiju, izmantoto klienta bibliotēku un konfigurāciju, kas izvēlas versiju. Pārbaudiet arī periodiskos darbus, atsevišķos importus un citas sistēmas, kurām ir savs savienojums ar to pašu piegādātāju. Viena veiksmīga darbība lietotāja saskarnē neapliecina visu šo ceļu saderību.

Webhook ir pakalpojuma nosūtīts paziņojums par notikumu. Tā datu formāts var būt piesaistīts citai versijai nekā jūsu pašu nosūtītie API pieprasījumi. Piemēram, Stripe versiju dokumentācija apraksta atsevišķu versijas izvēli pieprasījumiem un webhook galapunktiem. Šis ir konkrēta produkta piemērs; citu piegādātāju kārtība jānoskaidro viņu dokumentācijā.

Fiksējiet konfigurācijas pierādījumu bez atslēgām un citiem noslēpumiem. Ja atbildīgais nevar nosaukt izmantoto versiju, pirmais darbs ir inventarizācija. Pārslēgt nezināmu sākuma stāvokli ir grūti droši pārbaudīt un vēl grūtāk atjaunot.

Migrācijas termiņu ņemiet no konkrētā piegādātāja paziņojuma. Pārbaudiet, vai paziņojums attiecas uz visu pakalpojumu, vienu versiju, atsevišķu funkciju vai tikai jaunām integrācijām.

Pārvērtiet API izmaiņu sarakstu ietekmes matricā

Tehniska izmaiņa kļūst saprotama, kad tai blakus ir uzņēmuma darbība un sekas. Zemāk ir demonstrācijas matrica. Tās lauki un statusi jāaizstāj ar savas integrācijas dokumentētajām vērtībām.

Matrica jāizskata kopā ar procesa atbildīgo. Tehniski derīgs datums var nozīmēt citu biznesa momentu nekā agrāk. Lauks ar tādu pašu nosaukumu var vairs nebūt pieejams visos scenārijos. Savukārt jauns lauks, ko integrācija neizmanto, var neprasīt nekādu uzvedības maiņu.

Atzīmējiet arī dokumentēti neskartās darbības. Tas ierobežo izmaiņu apjomu un palīdz neiekļaut migrācijā nesaistītu pārbūvi. Nezināmu ietekmi neatzīmējiet kā drošu: tai vajadzīga atbilde no piegādātāja vai atsevišķs tests.

API kontrakta testi pārbauda datu nozīmi un darbības rezultātu

Kontrakta tests salīdzina integrācijas sagaidīto ievadi un rezultātu ar konkrēto API uzvedību. Pārbaude, ka atbilde ir nolasāma, ir tikai sākums. Uzņēmumam svarīgi, vai no atbildes izriet pareizā darbība.

Testa specifikācijā ierakstiet sākuma stāvokli, pieprasījumu vai notikumu, sagaidāmo datu kartējumu un aizliegto blakusefektu. Piemēram, atkārtoti saņemts apmaksas paziņojums drīkst atstāt pasūtījumu apmaksātu, bet nedrīkst radīt otru izsniegšanas uzdevumu. Šī prasība jāpārbauda atsevišķi no veiksmīgās pirmās apstrādes.

Izmantojiet anonimizētus vai sintētiskus piemērus. Saglabājiet problēmai svarīgo struktūru, piemēram, tukšu lauku, vairāku vienību pasūtījumu vai atceltu darbību, bet neiekļaujiet klientu datus tikai ērtības dēļ. Aizstājot identifikatorus, saglabājiet to savstarpējās saites, citādi piemērs pārbaudīs citu situāciju.

Nepieciešami arī robežgadījumi: nepazīstams statuss, daļēji pabeigta darbība, nokavēts paziņojums un atteikta piekļuve. Pie katra nosakiet, vai process apstājas pārskatīšanai vai var turpināties. Noklusējuma atzars “viss pārējais ir veiksmīgi” finanšu un pasūtījumu plūsmās ir īpaši bīstams.

Kā pārslēgt API, nepazaudējot ienākošos notikumus

Pārslēgšanas plānā nošķiriet notikuma saņemšanu no tā biznesa apstrādes. Ja apstrāde tiek īslaicīgi apturēta, jābūt pierādāmai vietai, kur saglabājas saņemtais darbs, un kārtībai tā turpināšanai. Šādas iespējas jāizveido vai jāpārbauda pirms migrācijas; tās nerodas automātiski līdz ar jaunu API versiju.

Stripe webhook dokumentācija brīdina par dublētiem notikumiem un to, ka piegādes secība nav garantēta. Savā integrācijā tādēļ pārbaudiet notikuma identitāti un atkārtotas apstrādes sekas. Divi notikumi par vienu objektu nav obligāti viens dublikāts: tie var aprakstīt atšķirīgas darbības.

Iedomāsimies pasūtījumu sistēmu, kas migrācijas laikā saņem apmaksas paziņojumu un vēlāk atcelšanas paziņojumu. Pārslēgšanas tests pārbauda gan abus notikumus, gan situāciju, kad vecais paziņojums pienāk atkārtoti. Mērķis ir panākt pareizu pasūtījuma stāvokli, ne tikai saskaitīt saņemtos ziņojumus.

Paralēla vecās un jaunās apstrādes darbināšana palīdz salīdzināt rezultātus tikai tad, ja otrā plūsma nekontrolēti neatkārto reālas darbības. Salīdzināšanas režīmā nedrīkst otrreiz nosūtīt rēķinu, veikt maksājumu vai izveidot noliktavas uzdevumu. Nosakiet, kurš ceļš konkrētajā brīdī drīkst veikt ierakstus.

API migrācijas atgriešanās plānam ir robežas

Iepriekšējās programmas versijas atjaunošana neatceļ jau izsūtītus dokumentus vai ārējā sistēmā veiktus ierakstus. Pirms pārslēgšanas jāzina, kuras darbības var atkārtot, kurām vajadzīga kompensējoša darbība un kuras pārskatīs cilvēks.

Stripe jaunināšanas instrukcija piedāvā konkrētam produktam paredzētu testēšanas un atgriešanās kārtību. To nevar pārcelt uz citu API kā universālu iespēju. Noskaidrojiet, vai vecā versija vēl pieejama, kādi ir tās atbalsta nosacījumi un vai atgriešanās nemaina vēl rindā esošo notikumu interpretāciju.

Vienojieties par apturēšanas pazīmēm: nepareiza statusu kartēšana, neizskaidrojami dublikāti vai neatbilstošas gala summas ir iemesls apturēt skarto apstrādi. Robežas un atbildīgo nosakiet pirms migrācijas, ne incidenta vidū. Arī manuālajam pagaidu procesam vajadzīga uzskaite, lai vēlāk automatizācija neizpildītu to pašu darbu vēlreiz.

Kā pieņemt pabeigtu API migrāciju

Pieņemšanai sagatavojiet izmantoto versiju sarakstu, ietekmes matricu un testa rezultātus. Pārbaudiet biznesa rezultātu abās savienotajās sistēmās. Zaļš integrācijas panelis var apliecināt veiksmīgu datu pārsūtīšanu, kamēr lietotājs redz nepareizi piesaistītu pasūtījumu.

Novērošanas periodu izvēlieties pēc procesa ritma. Ja noteikta darbība notiek tikai mēneša beigās, parasta darba diena to nepārbauda. Var izmantot kontrolētu testu, taču pieņemšanas protokolā jānorāda, kas pārbaudīts ar reāli novērotu plūsmu un kas ar testa datiem.

Šis darbs sākas pēc lēmuma par savienojuma veidu. Ja tas vēl nav pieņemts, skatiet API integrācijas un vienkāršākas datu apmaiņas izvēli. Savukārt strīdam par to, kura sistēma drīkst mainīt lauku, vajadzīgi vienotā patiesības avota noteikumi.

Biežākie jautājumi par API versijas maiņu

Vai bibliotēkas atjaunināšana pabeidz migrāciju?

Ne obligāti. Jāpārbauda faktiskā pieprasījumu versija, webhook formāts un uzņēmuma izmantotie scenāriji. Bibliotēkas saderība neapliecina pareizu biznesa rezultātu.

Vai jātestē viss no jauna?

Ietekmes matrica nosaka prioritāti, bet nepieciešama arī kritisko neskarto darbību regresijas pārbaude. Izvēli pamatojiet ar izmantotajiem savienojumiem un risku, ne ar piegādātāja izmaiņu saraksta garumu.

Vai migrāciju vienmēr var veikt bez pārtraukuma?

To nevar apsolīt pirms konkrētās integrācijas izvērtēšanas. Iespējams, vajadzīgs saskaņots ierobežojuma logs vai manuāls pagaidu process. Būtiski ir iepriekš zināt, kā saglabāsiet un saskaņosiet neapstrādāto darbu.

Ja vajadzīgs migrācijas izvērtējums, atsūtiet piegādātāja izmaiņu paziņojumu un integrācijas aprakstu, nevis piekļuves atslēgas. Biznesa procesu automatizācijas darbā tas ļauj sākt ar skarto procesu un saderības pārbaudēm, pirms vienoties par ieviešanas apjomu.